This is a beta release of documentation for Magento 2.4, published for previewing soon-to-be-released functionality. Content in this version is subject to change. Links to the v2.4 code base may not properly resolve until the code is officially released.

PayPal Website Payments Pro Hosted Solution payment method

PayPal’s Website Payments Pro Hosted Solution allows merchants to accept credit cards, debit cards, and PayPal payments directly on their websites. The merchant must be based in the United Kingdom to create a new integration with this payment method. PayPal continues to support merchants with existing integrations outside the UK.

This payment method is applicable to Direct Payment and Express Checkout implementations of the Website Payments Pro Hosted Solution.

PayPal’s product name for this payment method varies from country to country. PayPal Website Payments Pro Hosted Solution Integration Guide provides more information.

Website Payments Pro Hosted Solution workflow

The following diagram shows the workflow for placing an order when Website Payments Pro Hosted Solution is the selected payment method.

PayPal Website Payments Pro Hosted Solution sequence diagram

  1. The PWA client uses the setPaymentMethodOnCart mutation to set the payment method.

  2. The mutation returns a Cart object.

  3. The client runs the placeOrder mutation, which creates an order in Magento and begins the authorization process.

  4. Magento sends information about the order to PayPal and requests a secure URL that the PWA client will later use to connect to PayPal.

  5. PayPal’s response includes the secure URL.

  6. The placeOrder mutation returns an order ID. The order has the status payment pending.

  7. The client runs the getHostedProUrl query to retrieve the secure URL.

  8. Magento returns the secure URL in the secure_form_url attribute.

  9. The PWA client displays a payment form in an iframe rendered from the secure URL. When the customer completes the form, the client sends the payment information directly to the PayPal gateway, bypassing the Magento server.

  10. After PayPal processes the payment, the gateway runs a silent post request against the Magento server. As a result, Magento sets the order status to processing, and the order is ready to be invoiced.

  11. The PayPal gateway returns control of the customer’s browser to the client.

setPaymentMethodOnCart mutation

When you set the payment method for a Website Payments Pro Hosted Solution, you must set the code attribute to hosted_pro. In addition, the payload must contain a hosted_pro object, which defines the following attributes:

Attribute Data Type Description
cancel_url String! The relative URL of the page that PayPal will redirect to when the buyer cancels the transaction in order to choose a different payment method. If the full URL to this page is https://www.example.com/paypal/action/cancel.html, the relative URL is paypal/action/cancel.html
return_url String! The relative URL of the final confirmation page that PayPal will redirect to upon payment success. If the full URL to this page is https://www.example.com/paypal/action/return.html, the relative URL is paypal/action/return.html

Example usage

The following example shows the setPaymentMethodOnCart mutation constructed for the Website Payments Pro Hosted Solution payment method.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
mutation {
  setPaymentMethodOnCart(input: {
    cart_id: "H87OmEkvusP7ZPkd2634pQFxY4dKI3a4"
    payment_method: {
      code: "hosted_pro"
      hosted_pro: {
        cancel_url: "paypal/hostedpro/cancel"
        return_url: "paypal/hostedpro/return"
      }
    }
  })
  {
    cart {
      selected_payment_method {
        code
      }
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
{
  "data": {
    "setPaymentMethodOnCart": {
      "cart": {
        "selected_payment_method": {
          "code": "hosted_pro",
        }
      }
    }
  }
}