- v1.0.0-latest-prod
In your PayPal implementation, you are able to setup support for server-side shipping callbacks from PayPal Complete Payments.
In order to support those callbacks, a new endpoint was added in CartOperationServices that orchestrates the cart fulfillment & pricing updates, and returns the available shipping options.
For CartOperationServices to be able to understand the payload requests and responses, the payment gateway information must be passed to PayPal to parse and return in a framework-supported structure.
This means that CartOperationServices will call PaymentTransactionServices via the ExternalTransactionResultEndpoint with the request payload from PayPal, and PayPal will parse that into data for Cart to consume.
Then when CartOperationServices is ready to return a response to PayPal for the shipping callback, the cart data must be sent to the ExternalTransactionResultEndpoint to build out the appropriate response for the payment gateway.
DefaultPayPalCheckoutHostedService is the service implemented in the PayPal gateway module that is used to parse and understand this information.
This is the service that handles callbacks and requests from Hosted Solution pages. It is used in our PayPal gateway implementation to support shipping callbacks for PayPal’s shipping module.
On receiving a shipping callback, this method should be called to parse out the updated fulfillment information.
This method will take the request body passed on the ExternalFulfillmentCallbackDTO and parse it into the appropriate address and option information on ExternalGatewayFulfillmentUpdate to be updated on the cart.
In this PayPal implementation, this is responsible for parsing out the selected shipping options & purchase units.
When the cart has been updated, and we’re ready to return the response to the gateway caller, we need to be able to build out a gateway-specific response. This method will take the updated pricing & fulfillment information to build a response to the gateway. In this PayPal implementation, this will build the PurchaseUnits to return to PayPal, including the ShippingOptions for PayPal to display along with all the breakdown of pricing.
Best practices in web development is to ensure that actors are authorized for modification of any entities.
To further this end, we’ve ensured that an HMAC token is added during PayPal Order creation.
If you’re using the PayPal server-side callbacks within Broadleaf, it’s important to set the broadleaf.paypal-checkout.gateway.callback-token-hmac-key so that this HMAC token can be generated.
In the DefaultPayPalOrderService, the callback URL on the Order request is modified to append the token param, generated from the HMAC token configuration properties for the gateway.
This is done to provide security that the Order was created with the callback in the Broadleaf system, since PayPal doesn’t provide a security mechanism on the shipping callback endpoint.
During shipping callback, if the broadleaf.paypal-checkout.gateway.callback-token-hmac-key property is set, we will verify that the token exists and that it matches what the system is expecting to be returned.
So before we update the address on the cart, fulfillment options, or run re-pricing, we will parse out the request from the callback and verify the token.
The HMAC token is verified in DefaultPayPalCheckoutHostedService by generating the expected token and comparing the value to what we receive from the callback.
If it matches, we go ahead with the request. If it doesn’t, an exception is thrown and the request fails.