PayPal

Many merchants wish to offer shoppers the ability to pay seamlessly with PayPal, one of the most common payment methods. BlueSnap makes it easy to accept PayPal by connecting your PayPal and BlueSnap accounts, and then using the BlueSnap API to process PayPal payments.

📘

To offer PayPal as a payment option for your shoppers, you must have a PayPal Business or Premier account. If you do not yet have a PayPal account, you can sign up for one on the PayPal website.

Benefits

These are some features that are available when you offer PayPal:

• Payout to your PayPal account — PayPal funds are directly transferred to your PayPal Account. To avoid any double charging, BlueSnap deducts from its own transaction charges the standard transaction fees charged on your sales by PayPal.
• Shopper info saved and shipping info automatically updated — Shoppers already keep their details updated in PayPal, so you can automatically keep your own shopper records up-to-date by pulling the shipping info right from PayPal.

Supported Currencies

You can accept payments in several currencies by syncing your PayPal currency balances. We currently support the following currencies for PayPal:

PayPal Checkout Flows

The following sections describe the three types of PayPal checkout flows that BlueSnap APIs support. All checkout flows are compatible with PayPal's in-context-checkout, which displays PayPal screen as a popup within your site.

Standard Redirect (One-Step Flow)

This standard Express checkout flow directs the shopper to a PayPal page to make the purchase and then redirects the shopper back to your site after they complete the purchase. You specify the redirect URL with the pp-return-url property.

The following image illustrates he typical standard checkout flow:

Taxes and Fees (Two-Step Flow)

You might need to apply additional charges to a purchase, such as TAX/VAT or shipping fees according to your shopper’s location. You can retrieve this information with PayPal's two-step flow without asking your shopper for their address.

This checkout flow lets you direct your shopper to PayPal where the shopper approves the purchase, and then PayPal retrieves their address, calculates and applies additional charges, and displays the new final price to the shopper. After the shopper approves the final price, the transaction will take place for this final amount.

BlueSnap calls this the "two-step" checkout flow because you must send two API calls to BlueSnap, instead of a single call for the one-step checkout flow.

Delayed Capture (Three-Step Flow)

From a shopper’s perspective, the three-step checkout flow is identical to the previous option as the only difference is on the last step. After the shopper confirms the final amount, the merchant leaves the transaction as an approved authorization until the products are ready to be shipped or delivered.

This is convenient for merchants that want to sell physical goods that are not in stock when the transaction takes place. You direct your shopper through the purchase flow, allow them to approve the purchase and final amount, and you can capture the transaction when you are ready to deliver the goods.

BlueSnap calls this the "three-step" checkout flow because you must complete these transactions with three API calls to BlueSnap, instead of using a single call for the one-step checkout flow.

In-Context checkout

The In-Context checkout flow keeps the shopper in the context of your site while they complete the PayPal checkout. On a web solution, the PayPal page opens as a popup over the your site:

The mobile solution displays PayPal as a mobile-optimized, full-page checkout window:

In-Context checkout also has the benefit of shortening the checkout experience and providing a simplified design that is consistent across devices, as well as helping to improve conversion rates by making it easier for the shopper to complete checkout.

All out-of-box features for Express checkout are also supported for In-Context Checkout.

Supported Currencies

PayPal support for In-Context checkout but has limited availability. Supported currencies include the following:

• US Dollar
• Euro
• British Pound
• Canadian Dollar
• Australian Dollar
• Brazilian Real
• Danish Krone
• Norwegian Krone
• Polish Zloty
• Swedish Krona
• Swiss Franc

Browser Support

The following browsers support In-Context Checkout:

• Internet Explorer version 9 and later
• Chrome version 27 and later
• Firefox version 30 and later
• Safari version 5.1 and later
• Opera version 23 and later.

Enabling In-Context checkout

To enable In-Context Checkout, include the PayPal checkout.js JavaScript on the page that hosts your PayPal button.

📘

Note

Load and run the checkout.js script from //www.paypalobjects.com/api/. Do not download a local copy to your server and load it from there:

HTML

<script src="https://www.paypalobjects.com/api/checkout.js" async></script>

Next, you can enable In-Context checkout with the BlueSnap APIs:

• Payment API: Set the inContext property in the paypalTransaction resource to true.
• Extended Payment API: Set the pp-in-context property in the paypal resource to true.

After you enable In-Context checkout, the URL to the PayPal page looks like this:

https://www.sandbox.paypal.com/checkoutnow?token=XXX

Compared to the URL for an Express checkout flow, which looks like this:

<https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=XXX>

Payment API

The following sections describe how to use the Payment API to process PayPal transactions. For details about PayPal and the BlueSnap Extended API, see PayPal Guide.

📘

PayPal for merchant-managed subscriptions

If you are managing subscriptions yourself or through a third party and want to offer the PayPal payment method for recurring subscription payments, this option is also available via the Payment API. For a tutorial, see Processing merchant-managed PayPal subscription payments.

Prerequisites

Before you can process payments with BlueSnap, complete the following:

• Create a PayPal Business or Premier account. If you do not yet have a PayPal account, you can sign up for one on the PayPal website.
• Connect your PayPal and BlueSnap accounts. For details, see Connecting PayPal and BlueSnap.
• Review PayPal Checkout Flows to determine which checkout experience you want to provide your shoppers.

Step 1: Send the Request

Send a Create PayPal Transaction request to process your shopper's PayPal payment. The checkout flow determines the transaction-type value in the request content:

• Standard redirect (One-step flow) — AUTH/CAPTURE or omitted
• Taxes and Fees (Two-step flow) — AUTH_ONLY
• Delayed capture (Three-step flow) — SET_ORDER

The following examples show requests for each flow:

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "amount": 100,
    "vaultedShopperId": 12345678,
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "noShipping": 0,
        "cancelUrl": "http://www.cancelURL.com",
        "reqConfirmShipping": 1,
        "returnUrl": "http://www.returnURL.com"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "merchantTransactionId": "testtransaction1",
    "softDescriptor": "ABC COMPANY",
    "amount": "100.00",
    "currency": "USD",
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "paypalTransaction": {
        "transactionType": "AUTH_ONLY",
        "returnUrl": "http://www.returnURL.com",
        "cancelUrl": "http://www.cancelURL.com",
        "maxAmount": "120.00"
    }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "merchantTransactionId": "testtransaction1",
    "softDescriptor": "ABC COMPANY",
    "amount": "100.00",
    "currency": "USD",
    "payerInfo": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "paypalTransaction": {
        "transactionType": "SET_ORDER",
        "returnUrl": "http://www.returnURL.com",
        "cancelUrl": "http://www.cancelURL.com",
        "maxAmount": "120.00"
    }
}

These are some important properties in these request examples:

• Custom URLs — In the paypalTransaction object you need to specify two URLs:
  • returnUrl: URL where the shopper is redirected after completing the PayPal purchase. For example, a "thank you" page.
  • cancelUrl: URL where the shopper is redirected after cancelling the PayPal purchase.
• Shopper details — You can include any of the following shopper information:
  • No information about the shopper. For example, if it is a new or guest shopper, you can keep the request simple and not include any shopper details.
  • Some information about the shopper. For example, if you would like to use some of the shopper's information in order to customize the thank you page, then you can include the payerInfo object and send the shopper's name, address or other details.
  • A vaulted shopper ID: If you have already vaulted the shopper with BlueSnap, you can send the relevant vaultedShopperId within the altTransaction object.
• Shipping details from PayPal (vaulted shoppers only) — If you send a vaulted shopper in your Create PayPal Transaction request, you can retrieve the shopper's shipping details from PayPal. The vaulted shopper's record in BlueSnap will be automatically updated with the new shipping details from PayPal.

  📘

  Note

  This feature is not available if BlueSnap collects US sales tax or EU VAT for you.
  To retrieve shipping info from PayPal for a vaulted shopper:

  • In the paypalTransaction object, set the noShipping property to 0.
  • If you only want the shipping info to be retrieved if it has been specifically confirmed by the shopper in PayPal, then you should also include the reqConfirmShipping property, with the value set to 1.
• In-Context Checkout — To enable In-Contex Checkout, set the inContext property in the paypalTransaction object to true.

For additional details, refer to Create PayPal Transaction.

📘

Retrieving the shopper's phone number

The shopper’s phone number will not be automatically retrieved. If you are specifically interested in retrieving the phone number, please ensure you configure the Contact Telephone Number setting to Off. This setting is in your PayPal account under My Account > Profile > My selling tools > Website Preferences.

Step 2: Handle the Response

📘

Note

To secure and validate the PayPal transaction, assign a unique merchant transaction ID to every transaction. Then choose one of the following and code the logic for your returnUrl page:

• Call the Retrieve PayPal Transaction API using the merchantTransactionId, and validate the date and amount of the transaction.
• Or enable IPNs and code logic to check that an IPN is received for the PayPal transaction with the same merchantTransactionId, date, and amount.

A successful request returns a response with an altTransaction object and HTTP status code 200 OK. The altTransaction object contains the request properties and these additional properties:

• paypalTransaction object with the paypalUrl and orderId
• processingInfo

For example:

{
    "amount": 100,
    "vaultedShopperId": 12345678,
    "processingInfo": {"processingStatus": "PENDING"},
    "softDescriptor": "ABC COMPANY",
    "currency": "USD",
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-9GY47037JY601890L",
        "orderId": 9876543
    }
}

If you receive an error, refer to the PayPal errors listed on Alt Transaction Errors for guidance.

Step 3: Redirect to the paypalUrl

The response includes a paypalUrl field, which is the URL for the checkout page in PayPal where the shopper can complete the purchase. For example:

{
    ...
    "paypalTransaction": {
        "paypalUrl": "https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-9GY47037JY601890L",
        ...
    }
}

When you receive the response, you should redirect the shopper to this URL so they can finish the checkout process in PayPal.

Step 4: Redirect to a confirmation page

After the shopper completes checkout in PayPal, they are redirected to a confirmation page. The redirection process depends on the checkout flow. The checkout flow also determines which parameters are appended to the returnUrl from the Create PayPal Transaction request, which you can use to display transaction information to your shoppers:

Standard Redirect

The shopper is automatically sent to the "thank you" page you indicated in the return-url field of the original request. On this page, you might want to display the PayPal order number and other details about the purchase.

The standard redirect flow returnUrl includes the following parameters:

• ERROR: PayPal error code. 0 when successful, otherwise error code.
• INVOICE_ID: BlueSnap Invoice ID.
• PAYPAL_TRANSACTION_ID: Paypal transaction ID.
• SELLER_ORDER_ID: Your merchant transaction ID.

http://www.merchant-site.com/?ERROR=0&INVOICE_ID=1040698351&PAYPAL_TRANSACTION_ID=7D472473PR818573H&SELLER_ORDER_ID=<merchant-transaction-id>

📘

Note

If PayPal encounters an error, there will be an exception included as part of the URL.

Taxes and Fees (Two-Step Flow)

The shopper is automatically sent to the final confirmation page indicated in the return-url field in the original request.

The two-step flow returnUrl includes the following parameters:

• ERROR: PayPal error code. 0 when successful, otherwise error code.
• INVOICE_ID: BlueSnap’s Invoice ID.
• ACCOUNT_ID: BlueSnap’s vaulted shopper ID.
• SELLER_ORDER_ID: your merchant transaction ID

http://www.merchant-site.com/?ERROR=0&PAYPAL_TRANSACTION_ID=&ACCOUNT_ID=35714051&SELLER_ORDER_ID=<merchant-transaction-id>

📘

Note

You can use the vaulted shopper ID to perform a Retrieve Vaulted Shopper call, to retrieve the shopper’s information and update the final price accordingly.

Delayed Capture (Three-Step Flow)

The shopper is automatically sent to the final confirmation page indicated in the return-url field in the original request.

The three-step flow returnUrl includes the following parameters:

• ERROR: PayPal error code. 0 when successful, otherwise error code.
• INVOICE_ID: BlueSnap’s Invoice ID.
• PAYPAL_TRANSACTION_ID: PayPal PayerId.
• ACCOUNT_ID: BlueSnap vaulted shopper ID.
• SELLER_ORDER_ID: your merchant transaction ID.

http://www.merchant-site.com/?ERROR=0&PAYPAL_TRANSACTION_ID=BWGL6VEKKCDLY&ACCOUNT_ID=35714091&SELLER_ORDER_ID=<merchant-transaction-id>

📘

Note

You can use the vaulted shopper ID to perform a Retrieve Vaulted Shopper call, to retrieve the shopper’s information and update the final price accordingly.

Step 5: Complete the Process or Create Pending Authorization

You requirements in this step depend on the checkout flow:

Standard Redirect

This step is not applicable.

Taxes and Feeds (Two-Step Flow)

To finalize this order and have the payment processed, you must send an Update PayPal Transaction request with the following:

• orderId from the original transaction.
• New price (if applicable).
• transactionType set to CAPTURE.

Then, you can redirect your shopper to a final thank you page confirming transaction details.

Delayed Capture (Three-Step Flow)

In the previous step you presented your shopper with the final amount including any additional charges. Now, you need to create an Update PayPal Transaction request with the following:

• orderId from the original transaction
• New price (if applicable)
• transactionType set to DO_ORDER. This creates a pending authorization on your shopper's PayPal account for the actual amount including a new charges.

When you are ready to deliver the goods/services, you need to create a new Update PayPal Transaction request to complete the order.

📘

Note

A pending authorization can be left open several weeks.

If there were additional charges, you will need to modify the amount parameter with the final amount you wish to charge:

{
    "amount": "105.00",
    "currency": "USD",
    "paypalTransaction": {
        "orderId": "4006145",
        "transactionType": "CAPTURE"
    }
}

{
    "amount": "105.00",
    "currency": "USD",
    "paypalTransaction": {
        "orderId": "4006145",
        "transactionType": "DO_ORDER"
    }
}

Step 6: Capture the Transaction

🚧

Important

This step applies to the delayed capture (three-step flow) only.

When the goods or services are ready for delivery, and you informed your customer that you will debit the final amount from their PayPal account, you need to send a Update PayPal Transaction request. This request completes the transaction and moves it from a pending authorization to a captured charge.

To accomplish this, you will need to change the value of the transactionType parameter from DO_ORDER to CAPTURE.

It is still possible to modify this final amount again, but please make sure the shopper is aware of the final amount being charged and that they have received an updated receipt or invoice.