Symfony application for integrating with the Shoper platform, enabling external payment handling and managing the application lifecycle in the Shoper AppStore.

Based on: https://github.com/dreamcommerce/appstore-sf-mvc-example

This application is designed to integrate external payments into Shoper stores. After installation, it allows creating new payments and managing payment settings via the Shoper admin panel.

• Handles installation and uninstallation events (AppStore Events)
• Secure iframe authentication (hash, shopId, timestamp)
• Creation and configuration of external payments for the store
• User interface loaded in the Shoper admin panel (iframe)

https://developers.shoper.pl/developers/

The application uses a custom authentication system for iframe integration:

1. Shoper sends requests with shop ID, timestamp, and hash parameters
2. IframeAuthentication verifies the hash using HashValidator
3. Upon successful verification, the user is authenticated based on the shop ID

The application handles lifecycle events:

• Install: stores authorization code for API, creates a shop entry in the database, and initiates payment integration
• Uninstall: removes application data related to the shop
• Other events: can be extended with additional webhooks

• /app-store/event – endpoint for handling installation/uninstallation events (AppStore webhooks)
• /app-store/view/payments-configuration – payment configuration list view for all created payments from current application
• /app-store/view/payment-details – endpoint for viewing details of a specific payment in their own iframe
• /webhook/payment – endpoint for handling payment webhooks (POST, JSON). Validates headers and SHA using build in SignatureVerifier.

• PHP 8.2+
• Symfony 7+
• Composer

Note: You do NOT need to install PHP or Composer locally if you use the dev.sh script or Docker Compose. These are only required for manual setup or if you want to run the app without Docker.

You can set up the project in two ways:

1. Clone the repository and enter the app directory:

git clone <repo-url>
cd appstore-sf-external-payment-example/app

2. Then use the provided dev.sh script to automate the entire setup (environment, dependencies, Docker, migrations):

chmod +x ./dev.sh  # only once, if needed
./dev.sh

3. The application will be available at http://localhost:8080.

1. Clone the repository and enter the app directory:

git clone <repo-url>
cd appstore-sf-external-payment-example/app

2. Copy the .env.example file to .env and set the required environment variables:

   cp .env.example .env
   # Edit the .env file and set your secrets and database connection

3. Start the application:

   docker compose --env-file app/.env -f .docker/docker-compose.yaml up -d

4. The application will be available at http://localhost:8080.

Configure the application in Shoper AppTools and set the URLs to your local or production environment.

If you want to see the view in your devshop then you have to expose your local machine to the internet using ngrok or cloudflare tunnel. Example configuration for cloudflare tunnel and linux

  curl -L --output cloudflared.deb \
  https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb

 sudo dpkg -i cloudflared.deb

 sudo cloudflared tunnel run --token <token>

If you want to expose your local Symfony app to the internet (e.g. for Shoper AppTools integration), you can use ngrok:

# Download and install ngrok (if you don't have it)
# For Linux:
wget https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip
unzip ngrok-stable-linux-amd64.zip
sudo mv ngrok /usr/local/bin

# For Mac (Homebrew):
brew install ngrok/ngrok/ngrok

# Start ngrok tunnel for your local app (default Docker port 8080)
ngrok http 8080

After running ngrok, you will get a public HTTPS URL (e.g. https://abc123.ngrok.io).
Use this URL in Shoper AppTools as your app's endpoint.

This project uses a simple asset pipeline based on Node.js and Less for building CSS and copying JS files.

• Node.js (>=14)
• npm (>=6) or yarn

Install JS dependencies:

npm install

Build assets (CSS and JS):

npm run assets:build

This will:

• Compile assets/styles/payments-configuration.less to public/assets/payments-configuration.css
• Copy all JS files from assets/js/ to public/assets/

You should run this command after any change in frontend assets.

To enable payment handling, you must manually copy the JS snippet to your Shoper application snippet (for RWD skin).

1. Locate the file: assets/js/snippets/payment-data-handler.js
2. Copy the entire content of this file.
3. Change the URL 'API_URL' in the script.
4. In the Shoper admin panel, go to the AppTools and application snippet section (for RWD skin).
5. Paste the JS code directly into the snippet field.
6. Ensure the snippet is loaded on the cart or payment page.

Note: This JS file is not published automatically by Symfony and should not be treated as a standard frontend asset. It is intended for manual integration via the Shoper application panel.