This documentation is for the submodule of the Commerce PayPal project. Support / feature requests and module or documentation feedback should not be posted to these comments. Please use the project issue tracker instead.

Module description

PayPal Express Checkout (EC) is a redirected checkout / payment service where the customer primarily bypasses your normal checkout process to submit billing, shipping, and payment information at PayPal. Upon return to your site, this information will be used to populate the order, calculate the final total, and process the payment.

Customers get to PayPal by clicking the pictured "Checkout with PayPal" button from the shopping cart page and return from PayPal to a specific checkout page where they will review their order details, choose any additional options (like a shipping service or coupon code), and authorize payment via the "Pay now" button. This whole process is called the "shortcut flow" of Express Checkout.

Additionally, Express Checkout has a "mark flow" where your customers may choose to use your checkout form but then, selecting PayPal from the payment method radio buttons list, be redirected to PayPal to authorize payment via Express Checkout. In the mark flow, customers return straight to your checkout completion page with no intermediate confirmation checkout page being required.

Once payment has been completed, Express Checkout transactions may be updated through administrator action on the Drupal Commerce site or through the PayPal account. In the event that operations such as voids, captures, or refunds initiate in the PayPal account instead of through Drupal Commerce, PayPal will communicate the update via Instant Payment Notification (IPN) to the Drupal Commerce module, allowing the payment transaction to be updated as necessary.

Using PayPal Express Checkout

  1. Register for a PayPal Business account.
  2. Download and install the Commerce PayPal module package on your Drupal Commerce site.
  3. Enable the PayPal and PayPal Express Checkout modules in the Commerce (PayPal) modules category.
  4. Optionally, register for a PayPal Developer account and create a preconfigured "PayPal Express Checkout" sandbox account to test transactions without using live PayPal accounts or real money.

Payment method configuration

  1. Browse to Administration > Store > Configuration > Payment methods.
  2. You'll see here a list of rules that enable the payment methods defined on your site for use by your customers. Click on the edit link for the EC payment method.
  3. This page shows you the conditions (none by default) that must be met for EC to be available as a payment method and a single action enabling EC for use by your customers. Click the edit link for that action.
  4. You are now looking at the settings form where you can put in your API credentials and configure how Drupal Commerce should interact with PayPal EC. Here's a brief description of what you need to configure:
    • API username, API password, and Signature: to find these, login to your PayPal account and click on the Profile menu link:

      From there, choose Request API credentials from the Account information menu list:

      If you have more than one option, choose to setup your PayPal API credentials. Look for the option titled Request API credentials to create your own API username and password.. As a Drupal Commerce site owner, you need this option, and should click the View API Signature link. The page that appears will show you the precise API username, API password, and Signature that you should put in the EC settings form on your site.
    • PayPal server: set to Sandbox if you registered for a developer account and created a sandbox PayPal account for testing (recommended); switch to Live when you're ready to start selling or to perform real-money test transactions / refunds.
    • Default currency: PayPal's basic services only accommodate a handful of currencies around the world (see their currency charts). Choose the default currency you wish to accept payments in, and the EC module will convert order totals to this currency before redirecting the customer to PayPal for payment.
      Additionally, there's a checkbox beneath the currency setting that allows you to accept payment in any of the listed currency options. In this case, a multi-currency site could accept payment in any currency configured on the site, with the EC module only converting the transaction amount to the default currency if the customer is shopping in a currency not supported by PayPal.
    • Default transaction type: choose whether or not payment should be debited immediately from customers' PayPal or credit card accounts or merely authorized to be captured at a later date. Authorization only transactions are primarily used in instances where you are shipping physical products and need to delay capture until the product has actually shipped (or in instances where you otherwise need to review the details of an order before accepting it).
    • Express Checkout mode: the EC module supports "ECAO", or "Express Checkout Account Optional." By default, EC requires you to login with a PayPal account to submit payment, prompting customers without a PayPal account to create one before paying. However, with ECAO you can accept payment from customers without a PayPal account via a credit card form at PayPal. Selecting either the second or third Express Checkout mode will make ECAO available, with the difference being what screen (PayPal login vs. credit card form) is shown by default.
    • Shipping address collection: this option determines whether or not PayPal will prompt your customers to input a shipping address. For digital media sites, subscription sites, and others that do not require shipment to a physical address, this should be set to Do not ask for a shipping address at PayPal. However, for sites that do require shipment to a physical address, you should set this to one of the other two options depending on the desired behavior.
      Because customers may already have entered a shipping address (i.e. either through the Addressbook module's default address feature or by using the mark flow described above), the recommended option is to only ask for a shipping address if the order does not have one yet. When customers return from EC, their orders will be populated with the shipping address entered at PayPal.
    • API request / response and IPN logging: use the checkboxes and radio buttons under these two headings to configure the desired level of logging during module usage. During testing, it is recommended to enable full API request / response and IPN logging so you understand exactly how the module works and are able to debug any problems.
    • PayPal receiver e-mail addresses: input the primary e-mail address of your PayPal account and any additional e-mail address on the account that may be used to update EC transactions. If supplying multiple e-mail addresses, separate them with commas. When the EC module receives an IPN from PayPal, it checks the e-mail addresses listed here to validate the incoming notification, only updating transactions when the e-mail address in the IPN matches an e-mail address in this field.
    • Checkout form message: you can turn on a message to be displayed in the payment checkout pane if desired, indicating the customer should submit the form to proceed to PayPal. This is primarily useful when EC is mixed with other on-site payment options. If used, you should like give some attention in your theme to render the message more fittingly.

Checkout form configuration

In addition to the payment method settings form, you should also consider whether or not you need to configure the checkout form. The EC module defines a new checkout page called Confirm order between the payment redirect and completion pages and a checkout pane called Express Checkout review and confirm that should only be used on this special page.

This page is where EC customers using the shortcut flow return to after authorizing payment at PayPal. Here they can see their order updated to include any address information returned via PayPal (shipping address and billing name / country) and with prices recalculated to show any potential discounts, taxes, or other address related price alterations.

You can also choose to embed on this page any non-core checkout pane. None of the core Commerce checkout panes need to be embedded, as they will already be accounted for through the EC form and the Express Checkout review and confirm pane. However, checkout panes like coupon code entry, mailing list signup, or shipping service selection may need to be here to apply additional changes to the order that customers who use your on-site checkout form would normally see.

To embed a checkout pane here, simply click the configure link for the Express Checkout review and confirm pane and use the checkboxes list in the Checkout pane configuration fieldset to tell the pane which other checkout panes to include on the page. When the customer clicks the Pay now button at the bottom of this checkout page, the panes will be processed and the order updated before submitting a "DoPayment" request to the PayPal API to authorize or capture the final amount of the order.

Unified experience

The EC API supports a couple of parameters for customizing the look of the PayPal interface that we do not include in our API requests. Instead, PayPal recommends that users of this module customize these options through their PayPal account settings.

To find the designer, browse to My Account > Profile > Custom page styles (located in the Hosted payment settings menu list. You cannot edit the default PayPal design, so click the Add button, upload a logo and set your desired colors, save the design, and then make it your primary page design.

Ready to go live!

Because Express Checkout does not "fork" the checkout system (i.e. it integrates right into the normal checkout flow), any checkout completion rules you have configured should work just fine whether the customer pays on-site or at EC.

If you've configured your payment method and checkout form settings and tested both the shortcut flow and mark flow, you're ready to go live. During testing, make sure you've attempted every operation you expect your customers and the merchant to make to ensure Drupal Commerce is updating orders and transactions as expected.

For more information and documentation, please refer to the PayPal Express Checkout page on PayPal's developer site.

Comments

Jons’s picture

Paypal have changed their website.

To get sandbox API creds:

Create a sandbox business user: https://developer.paypal.com/webapps/developer/applications/accounts
Click down arrow next to name
Click Profile
Click API Credentials
Use these in Drupal Paypal Rule action configuration

Test
Create a personal user with an email and password, demo credit card values are provided

On checkout-review, select paypal and click 'continue to next step'- gets to PP login.
Put in the email/password when PP login screen comes up etc

To get Live API creds (I believe)
Using the 'classic' dashboard
From Profiles,
click 'My selling preferences'
click 'API access - Update'
On Request API credentials page select 'Request API signature', read and agree terms ..

morad7’s picture

I try to follow this guide to set up the EC Module https://commerceguys.com/sites/default/files/resources/Guide%20d%27int%C...
In Step 8 : I don't why they say "Fill in the field with « drupalcommerce » and move forward to the next step" this doesn't work, should I keep 'commerce-order' in the data selector field in the rule action edit form? I'm confused.
cheers

Infinitee’s picture

Login to PayPal and follow this link to the very elusive "Request API credentials" page on the PayPal site:

https://www.paypal.com/us/cgi-bin/webscr?cmd=_profile-api-add-direct-acc...