Edit

Dynamics 365 Payment Connector for PayPal

  • Article

This article provides an overview of the Microsoft Dynamics 365 Payment Connector for PayPal (PayPal payment connector). It includes a list of supported features and functionality, a guide to setting up and configuring the connector, troubleshooting information, and descriptions of some common issues.

Key terms

Term Description
PayPal Wallet Also known as the PayPal "button", PayPal Wallet describes the customer experience and integration supported by the PayPal payment connector.
Wallet A payment type that doesn't include traditional payment characteristics, such as the BIN range and expiration date, which are used to differentiate among credit and debit card types.

Microsoft Dynamics 365 Commerce offers an out-of-box integration for PayPal Wallet. When the PayPal payment connector is configured, the PayPal button is a selectable payment method as part of online order checkout. When users select PayPal, they're directed to complete their payment directly with PayPal and then are returned to the online storefront for order completion.

The PayPal payment connector is implemented using the same payments SDK that is used for credit card payments. To better support PayPal payments, support for non-credit card payments was enhanced with the addition of support for "wallet" payment types. Specifically, PayPal payments don't return a BIN range. To support PayPal and other wallet payments, a new mapping for payments was introduced that doesn't include BIN range. This new mapping can also be used to augment existing BIN range mapping for credit card payment methods. For more information, see Wallet payment support.

The PayPal payment connector isn't available in China. For other locales where Dynamics 365 Commerce is available, there are currently no restrictions.

Functional overview

PayPal Wallet in storefront

The PayPal payment connector supports the use of the PayPal Wallet, or PayPal button, for e-commerce payments. When the PayPal payment connector is configured for the online storefront, customers are presented with the option to pay using the PayPal button at the time of payment. When customers select the PayPal button, they're redirected to a PayPal Wallet mini-browser window where they're authenticated by PayPal and can select their method of payment. Upon successful authentication and selection of a payment method, customers are redirected back to the storefront with the PayPal payment loaded into the checkout form. When the order is placed, the PayPal payment is included as a payment line on the order, and is synchronized to Commerce headquarters.

For more information on PayPal Wallet, visit the PayPal Checkout page hosted by PayPal.

Fulfillment

Orders with PayPal payment lines are fulfilled in the same manner as orders that are paid using a credit card. When an order is created, the PayPal payment is added in an "authorized" state. Upon fulfillment, whether the order is shipped to the customer from a distribution center or picked up in a store, the payment authorization associated with the order is then "captured" using the same payments SDK requests used to capture credit card payments.

Fulfillment for PayPal orders supports incremental capture. This means that if an order is partially fulfilled and invoiced, a portion of the original authorization is captured and, rather than getting a new authorization for the remainder, the same original authorization is referenced when the remainder of the order is fulfilled.

Authorization expiration

Orders made using the PayPal payment connector should be fulfilled within 30 days. If an order can't be fulfilled or invoiced within 30 days, the original authorization expires. The PayPal payment connector doesn't currently support billing agreements. Recurring billing agreements, similar to recurring card references/tokens, are required to automatically generate new authorizations after original authorization expiration. This means that if an authorization expires, the order falls into a "do not process" state and the customer must be contacted to arrange for an alternate form of payment.

Order Intent

Beginning in Commerce version 10.0.30, the PayPal payment connector configuration in headquarters includes the OrderIntent field, which allows the configuration of the PayPal payment connector to operate with a saved order with the PayPal service for the online channel. After a payer approves an order, the PayPal payment connector sends a command to save the PayPal order, which allows for future references against the order within PayPal. For Commerce, this action means that a specific PayPal order reference can be reauthorized if a void was previously called. Merchants can also work with PayPal to configure the order expiry duration, and to customize functionality to reauthorize against a PayPal order if the original authorization isn't expired.

When you configure the PayPal payment connector in Commerce headquarters, the OrderIntent field can have two values:

  • Authorize: This configuration value is the default value. If the field is left blank, Authorize becomes the default value. Configuring the OrderIntent field with the Authorize value correlates to the PayPal processing instruction value of NO_INSTRUCTION. The order is authorized with PayPal and the authorization can't be modified when this value is used.
  • Save: Configuring the OrderIntent field with the Save value correlates to the PayPal processing instruction value of ORDER_SAVED_EXPLICITLY. When this value is used, order references are saved in the PayPal service.

Test the PayPal payment connector

Create a PayPal developer account

To test the PayPal payment connector, you must first create PayPal developer credentials and a PayPal sandbox environment.

  1. Go to the Test and go live page provided as part of PayPal's development resources.

  2. Select Get Started on the Test and go live page.

  3. On that page, select Log in to the Developer Dashboard.

  4. If prompted to sign in, select Sign up.

  5. Select Business Account, then select Next.

  6. Provide the email address you want to associate with your PayPal account and create a password for your PayPal account.

  7. On the next page, enter contact information details, then read the PayPal user agreement and Privacy statement. If you agree to the terms, select Agree and Create Account.

    Note

    The terms agreed to for the creation of a PayPal developer account are between the organization or individual creating the account and PayPal. Microsoft is in no way liable and makes no warranty as to the terms specified the agreement. These instructions are for informational purposes only.

  8. After you agree to the terms, specify your business type, and select Continue.

  9. Next, go to the PayPal Developer page and select Log in to Dashboard.

  10. Sign in using the credentials used when creating your PayPal account.

  11. In the developer dashboard, select the Default Application in the list of RestAPI apps.

  12. Note the Client ID and Secret for your sandbox account. These values are used to set up the PayPal payment connector in Dynamics 365 Commerce.

    Note

    To collect Client ID and Secret for a live environment, select the Live tab for the selected RestAPI app.

Set up the PayPal payment connector in Dynamics 365 Commerce

Map the PayPal wallet payment method to a processor payment method

Note

Some of these steps leverage a new capability for supporting wallet payment methods. For more information on this feature, see Wallet payment support.

  1. Go to Retail and Commerce > Channel Setup > Payment methods > Payment methods.
  2. Select New.
  3. Specify a Payment method ID and Payment method name, such as Wallet. Set the Default function to Wallet, and then select Save.
  4. Go to Retail and Commerce > Channel Setup > Payment methods > Card types.
  5. Select New.
  6. Specify an ID, such as PayPal. Set an Electronic payment name, such as PayPal. Set Type to Wallet, and then specify a name for the Issuer, such as PayPal. Select Save.
  7. Select the entry previously created and select Processor mapping.
  8. On the Processor payment method mapping page, select the previously created PayPal card type. In the middle column, select the Dynamics 365 Payment Connector for PayPal and select Add.

Note

The Processor payment method mapping capability adds a new table that must be synchronized to the channel database. To add this data to the Commerce scheduler, you need to initialize the Commerce scheduler. For details, please refer to documentation related to updating commerce scheduler configurations.

Set up the PayPal payment connector in payment services

Follow these steps to configure the PayPal payment connector in Payment Services.

  1. In Commerce headquarters, go to Accounts receivable > Payments setup > Payment services.

  2. On the Action Pane, select New, and then on the Setup tab, enter the following information.

    Field Description Sample value
    Payment service Enter the name of the payment service to configure. PayPal
    Payment connector Select the PayPal payment connector. Dynamics 365 Payment Connector for PayPal
    Test mode For the PayPal payment connector, in production and test environments you should set this field to False. False
    Default processor for credit cards This option should be set to No because the call center uses the default processor. No
    Bypass payment processor for zero transactions Specify whether this payment processor should be skipped for transactions that have a 0 (zero) amount. Yes

  3. On the Payment service account tab, enter the following information.

    Field Description Required Automatically set Sample value
    Assembly Name Autopopulated name of the assembly for the PayPal payment connector. Yes Yes Binary name
    Service account ID Autopopulated unique identifier for the setup of the merchant properties. This identifier is stamped on payment transactions and identifies the merchant properties that downstream processes should use (such as invoicing). Yes Yes Guid
    Merchant client ID Enter the sandbox Client ID collected from the PayPal developer dashboard under Default application. Yes Yes String
    Merchant API key Enter the sandbox Secret collected from the PayPal developer dashboard under Default application. Yes Yes String
    Supported currencies Enter the supported currencies, semicolon separated, to be supported for the PayPal payment connector. The default is USD. Yes Yes, but can be edited. USD; CAD
    Supported tender types Other payment connectors may support multiple tender types. For PayPal, the only payment method is PayPal. Yes Yes PayPal
    Supported payment method variants Other payment connectors may return multiple payment method variants. For PayPal, the only variant is PayPal. Yes Yes PayPal
    Environment This field is used to specify whether transactions should be sent to sandbox or live environments. Yes Yes Sandbox or Live
    OrderIntent This field is used to specify whether the order reference is saved in the PayPal service. No No Authorize (default behavior if left blank) or Save
    Enhanced totaling audit When this field is set to True, Commerce revalidates online order total calculations with the PayPal service prior to authorization. Introduced in Commerce version 10.0.35. No No True/False (If the field is blank, the default value is False. )

Note

When testing payments in a sandbox environment, the Environment field should never be set to live and live environment. Merchant client ID and Merchant API keys must never be used. Sandbox environments are for sandbox testing only.

Set up the PayPal payment connector for the online store

  1. In Commerce headquarters, go to Retail and Commerce > Channels > Online stores.

  2. Select the online store to add the PayPal payment connector.

  3. On the Online store page, on the Payment accounts FastTab, select Add.

  4. In Connectors, select Dynamics 365 Payment Connector for PayPal.

  5. Enter the following additional information.

    Field Description Required Automatically set Sample value
    Assembly Name Autopopulated name of the assembly for the PayPal payment connector. Yes Yes Binary name
    Service account ID Autopopulated unique identifier for the setup of the merchant properties. This identifier is stamped on payment transactions and identifies the merchant properties that downstream processes should use (such as invoicing). Yes Yes Guid
    Merchant client ID Enter the sandbox Client ID collected from the PayPal developer dashboard under Default application. Yes Yes String
    Merchant API key Enter the sandbox Secret collected from the PayPal developer dashboard under Default application. Yes Yes String
    Supported currencies Enter the supported currencies, semicolon separated, to be supported for the PayPal payment connector. The default is USD. Yes Yes, but can be edited. USD; CAD
    Supported tender types Other payment connectors may support multiple tender types. For PayPal, the only payment method is PayPal. Yes Yes PayPal
    Supported payment method variants Other payment connectors may return multiple payment method variants. For PayPal, the only variant is PayPal. Yes Yes PayPal
    Environment This field is used to specify whether transactions should be sent to sandbox or Live environments. Yes Yes Sandbox or Live
    OrderIntent This field is used to specify whether the order reference is saved in the PayPal service. No No Authorize (default behavior if left blank) or Save
    Enhanced totaling audit When this field is set to True, Commerce revalidates online order total calculations with the PayPal service prior to authorization. Introduced in Commerce version 10.0.35. No No True/False (If the field is blank, the default value is False. )

Set up the PayPal payment method for the online store

To set up the PayPal payment method for the online store, follow these steps.

  1. In the online store where the PayPal payment connector is configured, on the Setup tab, select Payment methods.
  2. Select New to add a payment method.
  3. In the Payment method field, select the PayPal payment method that you created earlier.
  4. In the Operation name field, select Pay card.
  5. In the Connector name field, select Dynamics 365 Payment Connector for PayPal.
  6. On the Posting FastTab, specify the posting details.
  7. Select Electronic payment setup, select New, and then, in the ID field, select the card type that you previously created for PayPal.
  8. Select Save, and then close the Electronic payment types and Online stores pages.

Note

When testing payments in a sandbox environment, the Environment field should never be set to live and live environment. Merchant client ID and Merchant API keys must never be used. Sandbox environments are for sandbox testing only.

After the above changes are made in Commerce headquarters, synchronize the changes using the 1070 distribution schedule.

Configure PayPal for the storefront checkout module

For details related to configuring storefront to use PayPal in the checkout module, see Payment module.

Enter a merchant relationship with PayPal

To create a Live merchant account with PayPal, visit the PayPal Checkout page for self-service or connect with a sales representative to discuss custom rates.

Additional resources

Payments FAQ

Checkout module

Payment module