# PayPal source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md PayPal is a supported browser payment method in the Mastercard Gateway. This page describes integration details specific to PayPal, including how to configure your PayPal business account to accept payments through the gateway, branding requirements, and so on. It is recommended that you read the [integration guidelines for browser payments](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/imp-brow-pay-int/index.md), before building a PayPal integration. ## Prerequisites {#prerequisites} To use PayPal as a payment method through the Mastercard Gateway, you must have a PayPal business account configured for the gateway. For details, see [Configuring your PayPal Business Account](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#configure-your-paypal-integration). To sign up for a PayPal business account, [click here](https://www.paypal.com/us/business/accept-payments/checkout). ## PayPal checkout experience {#paypal-checkout-experience} The following sections will help you choose a PayPal checkout experience that is most suitable for your site. ### Choosing a Checkout Flow {#choosing-a-checkout-flow} PayPal allows your payers to quickly and securely check out on your site, allowing them to use their PayPal account for payment and to optionally provide shipping information to the site. With PayPal, payers start and end the checkout process on your site. The gateway supports two types of PayPal checkout flows: 1. **Checkout with PayPal** 2. **Pay with PayPal**. Warning: **Venmo and Pay Later** Upgrade your SDK version to 1.3.0 to offer Venmo and Pay Later payment options to the buyers. For more information about Venmo and Pay Later, see [Pay with Venmo](https://developer.paypal.com/docs/checkout/pay-with-venmo/) and [Pay Later offers (US)](https://developer.paypal.com/docs/checkout/pay-later/us/). ### Checkout with PayPal {#checkout-with-paypal} The Checkout with PayPal flow allows you to redirect a payer from your site to PayPal through **Check Out with PayPal**. 1. A payer bypasses the normal checkout flow and checks out using the information stored in the PayPal account. 2. PayPal provides the name, email address, and shipping address to you from the payer's account. This action allows a faster checkout. 3. PayPal collects the shipping address from the payer at PayPal, which the payer can add or edit, if required. 4. After verifying the order details, the payer selects the **Continue** button. 5. The payer is redirected to your payment page for confirmation. 6. If required, you can change the order before accepting the payment. For example, adding shipping and handling charges based on the address returned from PayPal. #### Sample Checkout Flow {#sample-checkout-flow} The below diagram describes the **Checkout with PayPal** flow where the payer uses the shipping address as stored by PayPal. The payer reviews and confirms the payment on the merchant's site. ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/checkoutWithPayPal.png) The checkout flow is as follows: 1. A payer browses your site, selects a product and clicks **Checkout with PayPal** at the checkout page. 2. When the payer clicks the **Checkout with PayPal** button, you perform an Initiate Browser Payment call to the gateway, and redirect the payer to the PayPal URL returned in the response. 3. The gateway redirects the payer to PayPal. 4. The payer logs in to their PayPal account using the PayPal Login page. 5. The payer specifies the shipping address. The payer may select a shipping address previously stored with PayPal, or enter a new one. 6. The payer selects a funding source and proceeds with the payment by clicking the "Continue" button at PayPal. 7. The payer is redirected from PayPal back to your site, through the gateway. You retrieve the details of the transaction, including the payer's account, email and shipping address, using the Retrieve Transaction operation. 8. You present a review page to the payer based on this information (for example, you may wish to add shipping and handling charges). When the payer clicks the "Pay Now" button to process the payment, you submit a Confirm Browser Payment call to the gateway. Warning: The payer can choose to update the shipping address before clicking the "Pay Now" button. 9. The gateway sends a response with the transaction details, which indicates the success or otherwise of the payment, so you can present the status to the payer. ### Example Request {#example-request} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "browserPayment": { "operation": "AUTHORIZE", "paypal": { "paymentConfirmation": "CONFIRM_AT_MERCHANT" }, "returnUrl": "Https://test.com" }, "order": { "amount": "4.20", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } } ``` ### Pay with PayPal {#pay-with-paypal} The **Pay with PayPal** flow allows the payer to proceed through the normal checkout flow, entering their billing and shipping information into the site. When the payer is prompted to choose their payment method, the payer chooses the PayPal option placed on the site's billing page alongside other payment options. Unlike a **Checkout with PayPal** transaction, the site provides the payer's shipping address to PayPal. By default, you can choose not to display the shipping address and/or disable edits at PayPal. See [Display/Override Shipping Address](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#optional-displayoverride-shipping-address) below for information on how to implement this in your PayPal integration. The "Pay Now" button allows the payer to confirm the payment at PayPal before being redirected back to your site. This option allows you to provide a faster checkout experience to the payer as the payer completes the payment at PayPal. #### Sample Checkout Flow {#sample-checkout-flow-1} The below diagram describes the **Pay with PayPal** flow where the payer reviews and confirms the payment at PayPal. ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/payWithPayPal.png) The checkout flow is as follows: 1. A payer browses your site, selects a product and clicks **PayPal** at the checkout page. 2. When the payer clicks the **PayPal** button, you perform an Initiate Browser Payment call to the gateway, and redirect the payer to the PayPal URL returned in the response. 3. The gateway redirects the payer to PayPal. 4. The payer logs in to their PayPal account using the PayPal Login page. 5. The payer reviews the billing info details and confirms the payment by clicking the "Pay Now" button at PayPal. 6. The gateway sends a response with the transaction details, which indicates the success or otherwise of the payment, so you can present the status to the payer. ### Example Request {#example-request-1} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "browserPayment": { "operation": "PAY", "paypal": { "paymentConfirmation": "CONFIRM_AT_PROVIDER" }, "returnUrl": "Https://test.com" }, "order": { "amount": "4.20", "currency": "USD" }, "sourceOfFunds": { "type": "PAYPAL" } } ``` ### Choosing When to Confirm the Payment {#choosing-when-to-confirm-the-payment} With both **Checkout with PayPal** and **Pay with PayPal** checkout flows, you can choose to display a "Pay Now" button or a "Continue" button at PayPal. The "Pay Now" button allows the payer to confirm the payment at PayPal before being redirected back to your site. This option allows you to provide a faster checkout experience to the payer as the payer completes the payment at PayPal. The "Continue" button allows the payer to be redirected to your site to confirm the payment after viewing all the order details. This option allows you to change the order if necessary before accepting the payment (for example, adding shipping and handling charges based on the address returned from PayPal). Or, you can include other checkout steps, for example, upselling on your Confirm Order page. See [Payment Confirmation](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#browserpaymentpaypalpaymentconfirmation) for details on how to implement this in your PayPal integration. ### Choosing How to Collect the Shipping Address {#choosing-how-to-collect-the-shipping-address} Depending on the checkout flow, **Checkout with PayPal** or **Pay with PayPal** , you may choose to collect the payer's shipping address on your site or at PayPal respectively. By default, PayPal collects the shipping address from the payer at PayPal, which the payer can add or edit, if necessary. You can choose not to display the shipping address and/or disable edits. See [Display/Override Shipping Address](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#optional-displayoverride-shipping-address) for information on how to implement this in your PayPal integration. ## PayPal Integration {#paypal-integration} ### PayPal as a checkout option in Hosted Checkout {#paypal-as-a-checkout-option-in-hosted-checkout} If you are using the Mastercard Gateway payment page (Hosted Checkout) PayPal will automatically be offered as a checkout option to your payers if your payment service provider has configured the PayPal acquirer link on your merchant profile. For details, see [Browser Payments through Hosted Checkout Integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/imp-brow-pay-int/index.md#browser-payments-through-hosted-checkout-integration). Warning: To use the PayPal payment method through the PayPal Smart button on the checkout, use Mastercard Gateway API Version 76 or later. ### PayPal as a checkout option on your payment page {#paypal-as-a-checkout-option-on-your-payment-page} Tip: Integrate with API version 100 for full compatibility. PayPal is supported as a checkout option on your payment page if you are integrated to API version 50 or later. Submit the [Initiate Browser Payment](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#browser-payment) request from your server-side application to initiate the PayPal interaction. The payer is redirected from your site to PayPal to log in and complete the payment details. For more information, see [PayPal through Direct Payment](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#paypal-through-direct-payment). ### PayPal through Direct Payment {#paypal-through-direct-payment} The following fields in the Initiate Browser Payment request are either specific to PayPal or have a specific usage in the PayPal integration. For other details, see [Browser Payments through Direct Payment Integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/imp-brow-pay-int/index.md#browser-payments-through-direct-payment-integration). * `sourceOfFunds.type` = PAYPAL * `browserPayment.operation` = AUTHORIZE or PAY With PayPal, funds can be held for three days (honor period) from the time the authorization occurred. If you still wish to capture the funds after three days, you can use the [Update Authorization](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#authorization-updates) operation or initiate through Merchant Administration. Alert: By default, your PayPal merchant account is configured for single captures only. If you wish to change the configuration to support multiple captures, contact PayPal. **Operation Field API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) ### browserPayment.paypal.paymentConfirmation {#browserpaymentpaypalpaymentconfirmation} When initiating a PayPal payment, you must specify if you want the payer to confirm the payment at PayPal or your site. **Payment Confirmation Field API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) If confirming at the provider (PayPal), the PayPal displays a "Pay Now" button, which allows the payer to confirm the payment at PayPal before being redirected to your site. Submit a Retrieve Transaction request to the Mastercard Gateway to determine the success or otherwise of the payment. If confirming on your site, the PayPal displays a "Continue" button, which allows the payer to be redirected to your site where the payer can confirm the payment. Send a Retrieve Transaction request to the gateway to retrieve details on whether the payer has continued with the payment or not. If the payer continues with the payment on your site, you need to send a Confirm Browser Payment call to confirm the payment with PayPal. The Confirm Browser Payment response will contain information about the success or otherwise of the payment. **Confirm Browser Payment API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) In both cases, if the payment is successful, the Retrieve Transaction returns: * the email address on the payer's PayPal account * the account holder name on the payer's PayPal account * the payer ID associated with a payer's PayPal account' * the shipping address details ### Example Request {#example-request-2} ```json { "apiOperation": "CONFIRM_BROWSER_PAYMENT", "order": { "amount": "4.20", "currency": "USD" } } ``` ### \[Optional\] Display/Override Shipping Address {#optional-displayoverride-shipping-address} You can manage how the payer provides you with a shipping address using two fields: * `browserPayment.paypal.displayShippingAddress` --- when set to true (default), the shipping address is displayed at PayPal. **Display Shipping Address Field API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) * `browserPayment.paypal.overrideShippingAddress` --- when set to true (default), the payer can change the shipping address at PayPal. **Override Shipping Address Field API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) By default, PayPal collects the shipping address from the payer at PayPal for you. If you choose to collect the shipping address from the payer on your site, and you do not want PayPal to display the shipping address to the payer, you must set `browserPayment.paypal.displayShippingAddress` to false. This also applies when a shipping address is not required for an order (for example, digital products only). The gateway will always return the shipping address in the Retrieve Transaction response if the address was supplied in the Initiate Browser Payment request or if `browserPayment.paypal.displayShippingAddress` is set to true. Warning: You should use the shipping address returned in the transaction response in case the shipping address was changed by the payer at PayPal. Note that PayPal validates city, state, ZIP code combinations for U.S. shipping addresses. ### \[Optional\] Line Item Details {#optional-line-item-details} You can specify line item details in the Initiate Browser Payment request to provide payers with all the order details before they confirm the payment. Consumer research shows that more buyers complete purchases when they see the individual items and other details of an order during PayPal checkout. Hence, it is recommended that you provide order information when you initiate a PayPal checkout to encourage payers to continue with the payment rather than dropping out. Line items are considered provided if the item name or unit price is specified. For more information on line item details, see [Line Item Data](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/data-and-reporting/supp-data/index.md). ## How to Interpret the Transaction Result {#how-to-interpret-the-transaction-result} The table below shows the transaction Response Codes for the possible scenarios that you may encounter after initiating a browser payment. | Initiate Browser Payment Response | What This Means... | |-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | response.gatewayCode=SUBMITTED result=SUCCESS | Redirect the payer using the URL provided in the response. | | response.gatewayCode=SUBMITTED result=FAILURE or PENDING or UNKNOWN | Submit another INITIATE_BROWSER_PAYMENT request. | | **Retrieve Transaction/Retrieve Order Response** | **What This Means...** | | response.gatewayCode=APPROVED result=SUCCESS | The payment is successful. | | response.gatewayCode=PENDING result=PENDING | The payment is pending a review in the PayPal system. See [Pending Payments](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#pending-payments). | | response.gatewayCode=CANCELLED result=FAILURE | The payer has canceled the interaction for this payment. Offer the payer the option to try another payment method. | | response.gatewayCode=DECLINED or INSUFFICIENT_FUNDS or NOT_SUPPORTED result=FAILURE | The payment was declined by PayPal. | | response.gatewayCode=ACQUIRER_SYSTEM_ERROR result=FAILURE | The acquirer was unable to process the transaction. You may want to inquire with the acquirer the reason for payment failure, or you can try RETRIEVE_TRANSACTION again. Or, you can offer the payer the option to try another payment method. | | response.gatewayCode=SYSTEM_ERROR result=FAILURE | The gateway was unable to process the transaction. | | response.gatewayCode=TIMED_OUT result=FAILURE | The interaction between the payer and the PayPal system was not successfully completed, for example, the gateway did not receive a redirect of the payer's browser from the merchant within 24 hours or the gateway was unable to retrieve the interaction details between the payer and the PayPal system hence the payment is incomplete. | | response.gatewayCode=UNKNOWN result=UNKNOWN | The gateway was unable to find out about the success or otherwise of the payment. | ## Authorization Updates {#authorization-updates} You can update the authorization honor period and/or increment authorization amounts for valid the PayPal authorization transactions using the Update Authorization operation or through Merchant Administration. To allow this, you must have the "Update Authorization" privilege enabled on your merchant profile by your payment service provider. For more information, see [Update Authorization](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/integrate-direct-payment/transaction-operations/index.md#update-authorization.md). It is recommended that you update an authorization after the initial three days (honor period) to ensure that funds are still available. A reauthorized payment has a new 3-day honor period. The 3-day honor period can be updated at most once within the 29-day validity period. You can update an authorization once for up to a maximum of 115% or USD $75 of the originally authorized amount. ## Captures, Refunds, and Voids {#captures-refunds-and-voids} For PayPal payments, you can capture the authorized amount in part or in full of the originally authorized amount using the Capture operation or through Merchant Administration. You can refund payments processed through PayPal in part or in full for Pay and Capture transactions. You can submit Refund requests using the Refund operation or using Merchant Administration. You can void any authorized transaction if capture attempts have failed or you can refund a Pay transaction to reverse the payment. You can submit the Void or Refund request using the API operation, Void and Refund or through Merchant Administration. ## Pending Payments {#pending-payments} The gateway may return a status of PENDING in the transaction response. For example, if the transaction is currently under risk assessment at PayPal. If the status is pending and if you have configured your own fraud management filters, you should log on to your PayPal business account and review the payment. PayPal will notify the gateway when the status of a pending transaction is updated by PayPal. ## Billing Agreement and Recurring Payments {#billing-agreement-and-recurring-payments} Using Checkout with PayPal or Pay with PayPal, you can set up a billing agreement for a payer, which allows you to initiate a reference transaction (subscription/recurring or on-demand payments) against this billing agreement without additional consent from the payer. For more information, see [Billing Agreement and Recurring Payments](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/bill-agree-recc-pay/index.md). ## Configure your PayPal Integration {#configure-your-paypal-integration} To process transaction through PayPal, you must grant the gateway permission to submit transactions requests to PayPal on your behalf. To grant third-party permission, you must log in to the Merchant Administration portal. On the PayPal configuration page, you can see the PayPal merchant acquirer links that your payment service provider has configured for you. If you have not granted the third-party permission on the acquirer link, the Account ID field remains empty. Hence, you must grant permission to the gateway so that the gateway can make API calls on your behalf. ### For new the PayPal account {#for-new-the-paypal-account} To grant third-party permissions for the PayPal APIs with a new email account: 1. To grant the third-party permission for a specific acquirer link, select **Enable**. 2. Enter the required details on the **PayPal** page, and then select **Next**. 3. Enter the required details, and then select the **User Agreement, Privacy Statement** check boxes. 4. Select **Agree and Create an Account**. 5. Enter the business-related information, and then click **Next**. 6. Enter the user-related information, and then click **Submit** . The sign-up confirmation page displays the instructions to activate your PayPal account. 7. Activate your PayPal account as per the instructions sent to the email address that you have entered at the time of sign-up. 8. Follow the instruction on the screen to return to the Merchant Administration page. The third-party permissions required for the specific PayPal acquirer link are granted. The status gets enabled and the PayPal Account ID is displayed. 9. To revoke the third-party permission, select **Disable** and to update any information, select **Update** . Due to any issue if the third-party permission fails, an error message is displayed. ### For registered the PayPal account {#for-registered-the-paypal-account} To grant third-party permissions for the PayPal APIs with a registered email account: 1. To grant the third-party permission for a specific acquirer link, select **Enable**. 2. Enter the required details on the **PayPal** page, and then select **Next**. 3. Enter your credentials, and then select **Log In** . You have successfully signed up and integrated PayPal. 4. Follow the instruction on the screen to return to the Merchant Administration page. The third-party permissions required for the specific PayPal acquirer link are granted. The status gets enabled and the PayPal Account ID is displayed. 5. To revoke the third-party permission, select **Disable** and to update any information, select **Update** . Due to any issue if the third-party permission fails, an error message is displayed. ## Enhanced seller protection {#enhanced-seller-protection} You can submit additional payer data in the Initiate Browser Payment and in the subsequent Pay or Authorize requests after performing Tokenize Browser Payment to allow PayPal to perform a risk assessment of the transaction before the transaction is processed. The data in the following fields is used by PayPal to perform a pre-transaction risk management evaluation: * `device.fingerprint`: A unique identifier for the device that can be generated using the PayPal FraudNet Javascript library. This allows PayPal to perform a risk assessment of the transaction. * `risk.custom`: You can provide additional data about the payment in this field. You must have an agreement with PayPal about the values you wish to provide. For example, `risk.custom.headOfficeLocation`=London UK. * `sourceOfFunds.token`: The token ID that identifies the billing agreement details (as received from PayPal) on the gateway. You can use this token ID for one-time and recurring payments. For more information, see [Billing Agreement and Recurring Payments](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/bill-agree-recc-pay/index.md). Warning: For direct payment, the `sourceOfFunds` is PayPal. ## Excessive refund {#excessive-refund} Excessive Refunds must be enabled at the PayPal site. You can capture the excess authorised amount either through the Capture request or the Merchant Administration. An excess capture of up to 115% of the original authorized transaction is allowed. You can refund the excess payments processed through PayPal for the Pay and the Capture transactions. You can submit the Refund requests either through the Refund operation or Merchant Administration. For excess refund, include the amount that is in excess of the original transaction amount. To refund in excess of the captured amount, ensure that you are enabled for excessive refunds on your PayPal merchant profile. If your PayPal profile is enabled for excessive refunds, ensure to configure your Mastercard Gateway merchant profile for the same. ## Testing your Integration {#testing-your-integration} The Mastercard Gateway provides a PayPal simulator that allows you to ***test your integration*** for using the PayPal functionality through the gateway. Warning: After you are onboarded, the PayPal Sandbox ID is set to a dummy value so that you can test your integration with your test profile. Once your third-party permission is granted, the dummy value will get replaced with the actual PayPal account ID.