Configure PayPal-Checkout Checkout (formerly PayPal-Plus)

With the modern PayPal Checkout, you have all important payment methods in one widget, a single API, and a consistent user experience – significantly more convenient and conversion-boosting for you and your customers.

Attention:

PayPal-Checkout Checkout requires the Pro version of the shop extension!

Attention:

The PayPal-Checkout Checkout requires the entry of the full URL in the site configuration of your TYPO3 instance!

Attention:

The payment options of the PayPal-Checkout Checkout are not configurable. Depending on the country and the possible payment options are displayed.!

stateDiagram-v2
    %% Frontend
    [*] --> prepared : Customer builds cart\nand starts checkout
    prepared --> ordered : Checkout completed
    %% Stripe payment
    ordered --> paid : Payment confirmed by PayPal\nConfirmation email\nInvoice number
    %% Shipping & completion
    paid --> shipped : Shipping performed manually
    paid --> processed : Completed without shipping\n(e.g., digital service)
    shipped --> processed : Completed after shipping
    %% Special case: cancellation before payment
    prepared --> canceled : Payment failed\nor was cancelled
    canceled --> prepared : Payment can be retried
    %% Conditions
    note right of processed
      Conditions:
      - paid_date MUST be set
      - shipped_date MUST be set
        if shipping has occurred
    end note

Further actions:

• Returns: Possible as soon as the goods have been shipped – i.e., in the status shipped or processed.
• Deletion: Deleting an order is only possible in the status prepared.

PayPal-Checkout Account

You will need a PayPal account. Log-in to PayPal and open https://developer.paypal.com. Go to My Apps & Credentials in the menu and create a new app. Take note of whether you want to create a Live or a Sandbox account. After creating it, you should have the following information

• (Sandbox) Account: This is an email address.
• Client ID: This is a hash value that identifies the client.
• Secret: This is also a hash value. Make sure you keep it secret!

For testing purposes you will need an extra account which you can set up under https://developer.paypal.com/developer/accounts/.

Checkout configuration

• active Activate/deactivate checkout
• checkoutPid Enter the page Uid of the checkout page.
• successPid Enter the page Uid of the success page. This is the page you will be redirected to after successful payment.
• service The checkout service PHP class is assigned here. This can be modified if the process needs to be changed.
• sandbox Activate/deactivate the sandbox.
• payPalCheckoutClientId Enter the client ID of the (sandbox) account created in PayPal.
• payPalCheckoutSecret Enter the Secret of the (sandbox) account that was created in PayPal.

Add additional actions after a successful payment

If you need actions to be carried out after successful payment, use the PayPalCheckoutPaid event listener.

1. Create a new event listener:

   <?php
   namespace YourVendor\YourExtension\EventListener;
   use CodingMs\ShopPro\Event\BasketOrder\PayPalCheckoutPaidEvent;
   class DoSomeThingEventListener
   {
       public function __invoke(PayPalCheckoutPaidEvent $event): void
       {
           /* Do something */
       }
   }

2. Then register the event listener in Configuration/Services.yaml:

   services:
       YourVendor\YourExtension\EventListener\DoSomeThingEventListener:
           tags:
               - name: event.listener
                 identifier: 'myListener'
                 event: CodingMs\ShopPro\Event\BasketOrder\PayPalCheckoutPaidEvent

Debugging

If a callback does not work, you can activate debugging. Read how this works in the How To/Debugging section.

Internal Process

You go through three main phases:

1. Create Order & Retrieve Order IDIn PayPalCheckoutCheckoutService → getPaymentResource():

   • You transmit all order data to PayPal on the server side and receive the corresponding Order ID (Payment Resource).
   • Before retrieving the order, save the sent parameters in basketOrder.callbackParameter so that you can trace which values ​​were transmitted in case of an error.
   • After a successful retrieval, also save the response from PayPal in basketOrder.callbackParameter. This way, you can later find the appropriate order ID at any time using basketOrder.uid and validate the payment.

2. Frontend: Initialize PayPal buttons & trigger paymentIn your ConfirmOrder.html:

   • You retrieve the previously saved order ID and pass it when initializing the PayPal buttons.
   • You use the PayPal widget to complete the payment process during checkout.
   • As soon as the widget signals via onApprove that the buyer has authorized the payment, you activate the "Confirm Order" button. Clicking it starts the final Confirm Order action in the backend.

3. Validate payment & complete orderIn the BasketOrderController → confirmOrderAction:

   • You load the data record using the basketOrder.uid and read the order ID from basketOrder.callbackParameter.
   • Use this order ID to query PayPal for the current status (GET /v2/checkout/orders/{orderId}) or perform a capture if necessary.
   • Save the response again in basketOrder.callbackParameter.
   • If your request receives the status COMPLETED, mark the order as paid and initiate all further processes (shipping, invoicing, etc.). For any other status, abort and inform accordingly.

Configure PayPal-Plus IPN

If you are still using the old PayPal-Plus (up to shop version 5.2.0), you must activate IPN in your PayPal account. This is no longer available in the PayPal interface, as it is outdated and the new PayPal Checkout should be used.

1. Log in to PayPalLog in to your live account at https://www.paypal.com.

2. Open Account SettingsClick the gear icon in the top right and select "Account Settings".

3. Access Website Payment SettingsScroll to the menu item "Website Payment Settings" or go directly to:

    https://www.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-ipn-notify

4. Activate IPN

   • Select "Edit IPN Settings".
   • Enable **"Instant Payment Notifications (IPN)".
   • Enter a valid HTTPS address as the URL (e.g., your callback URL).
   • Save the setting.

     Note: The URL does not have to be your final notify_url; it can be any valid HTTPS address.

5. Check IPN History

   • In the dashboard, open "Activities → All Transactions", select a transaction, and click "View IPN History" at the bottom or go directly to:

     https://www.paypal.com/cgi-bin/webscr?cmd=_display-ipns-history

   • There you can see whether PayPal has sent notifications and what HTTP status your server returned.