diff --git a/README.md b/README.md index 0e85d21..e426758 100644 --- a/README.md +++ b/README.md @@ -14,24 +14,21 @@ This boilerplate provides a starting point for integrating payment gateways with Relation of Extensions with Fynd Platform. -* Forward payment -![Forward payment](https://cdn.pixelbin.io/v2/doc/original/moonlight/Extensions/payment_extension/payment_forward) +- Forward payment + ![Forward payment](https://cdn.pixelbin.io/v2/doc/original/moonlight/Extensions/payment_extension/payment_forward) -* Get payment status -![Get payment status](https://cdn.pixelbin.io/v2/doc/original/moonlight/Extensions/payment_extension/get_payment_status.svg) +- Get payment status + ![Get payment status](https://cdn.pixelbin.io/v2/doc/original/moonlight/Extensions/payment_extension/get_payment_status.svg) +- Refund payment + ![Get payment status](https://cdn.pixelbin.io/v2/doc/original/moonlight/Extensions/payment_extension/payment_refund.png) -* Refund payment -![Get payment status](https://cdn.pixelbin.io/v2/doc/original/moonlight/Extensions/payment_extension/payment_refund.png) - - -* Get refund status -![Get payment status](https://cdn.pixelbin.io/v2/doc/original/moonlight/Extensions/payment_extension/get_refund_status.svg) - +- Get refund status + ![Get payment status](https://cdn.pixelbin.io/v2/doc/original/moonlight/Extensions/payment_extension/get_refund_status.svg) ## πŸ”— Quick Links -| [🌐 Fynd Platform](https://platform.fynd.com/) | [🀝 Fynd Partners](https://partners.fynd.com/) | [πŸ“š Documentation](https://documentation.fynd.com/) | [πŸ“š Dev Documentation](https://partners.fynd.com/help/docs/partners/getting-started/overview) | +| [🌐 Fynd Platform](https://platform.fynd.com/) | [🀝 Fynd Partners](https://partners.fynd.com/) | [πŸ“š Documentation](https://partners.fynd.com/help/docs/partners/getting-started/overview) | ## πŸ› οΈ Prerequisites @@ -48,9 +45,9 @@ Before setting up the extension, make sure you have the following installed: This guide provides a step-by-step process for building and setting up a payment extension, with two main approaches depending on your preferred technology stack. ## Table of Contents + - [Approach to Building Your Payment Extension](#approach-to-building-your-payment-extension) - [Option 1: Using Node + React Payment Extension Template](#option-1-using-node--react-payment-extension-template) - - [Option 2: Building from Scratch](#option-2-building-from-scratch) - [Setting Up in the Fynd Partners Panel](#setting-up-in-the-fynd-partners-panel) - [Step 1: Register on the Partners Panel](#step-1-register-on-the-partners-panel) - [Step 2: Create a New Payment Extension](#step-2-create-a-new-payment-extension) @@ -66,44 +63,44 @@ This guide provides a step-by-step process for building and setting up a payment ## Approach to Building Your Payment Extension ### Option 1: Using Node + React Payment Extension Template + For those using Node and React, a pre-implemented template is available, which includes: + - OAuth support for authentication - Required endpoints for processing requests - Frontend code for collecting payment gateway credentials from merchants -### Option 2: Building from Scratch -If you prefer to build your payment extension from scratch, follow these steps: - -1. **Registering a Payment Extension**: Start by creating a payment extension on the partner panel. This will provide you with an Extension API Key and Extension API Secret. -2. **Implementing the Extension**: Set up necessary flows for installation, activation, payments, and refunds. -3. **Best Practices and Troubleshooting**: Familiarize yourself with best practices and troubleshoot common issues. -4. **Testing the Extension**: Ensure your extension works seamlessly for both merchant and customer flows. - --- ## Setting Up in the Fynd Partners Panel ### Step 1: Register on the Partners Panel + - Register on the Fynd Partners Panel. - After registration, you can join an existing Partner Organization or create a new one. ### Step 2: Create a New Payment Extension + - Once you’re part of an organization, navigate to **Extension > Create Extension**. - Choose **Start from scratch**, select **Extension Type** as **Payments**, fill in the required details, and click **Create Extension**. ### Step 3: Install Your Payment Extension + - Go to **Sales Channel > Settings > Cart & Payments > Payments > General Settings > Payment Options**. - Find your new extension under **Payment Options**, select it, and install it. ### Step 4: Configure the Extension + - In the **Payment Options** section, click on your extension. - Configure the extension for web, iOS, or Android as per your requirements. ### Step 5: Access Extension Credentials + - Click the three dots in the top-right corner (near the save button) and select **Credentials** from the dropdown. - The extension UI will appear, allowing you to input the necessary credentials. ### Step 6: Complete the Setup + - Fill in the required credentials. - 🎊 Your payment extension is now fully configured and ready for use! 🎊 @@ -125,8 +122,8 @@ For more detailed examples and additional languages, refer to the provided guide --- ## Congratulations! -You have successfully set up your payment extension on the Fynd platform. +You have successfully set up your payment extension on the Fynd platform. ### πŸ’» Local Setup @@ -152,71 +149,69 @@ You have successfully set up your payment extension on the Fynd platform. 3. **πŸ“ Use Git to clone the repository to your local machine and navigate into the project directory.** - ```bash - git clone https://github.com/fynd-platform/GA4-Extension - ``` + ```bash + git clone https://github.com/gofynd/payment-extension-boilerplate.git + ``` 4. **πŸ“¦ Install Backend Dependencies.** Ensure you have Node.js (v16.x.x or above) installed. - ```bash - npm install - ``` + ```bash + npm install + ``` 5. **πŸ“¦ Install Frontend Dependencies.** - ```bash - cd web - npm install - ``` + ```bash + cd web + npm install + ``` -6. **πŸ”§ Create build of frontend Vue project.** +6. **πŸ”§ Create build of frontend React project.** - ```bash - npm run build - ``` + ```bash + npm run build + ``` 7. **πŸ› οΈ Configure Environment Variables.** - Open the `app/fdk/config.js` file in your project directory. Update the `EXTENSION_API_KEY` and `EXTENSION_API_SECRET` environment variables in `extension.api_key` and `extension.api_secret` with the values obtained from the Partners Panel. These should be set as the default values for the `config` variables. - + Open the `app/config.js` file in your project directory. Update the `EXTENSION_API_KEY` and `EXTENSION_API_SECRET` environment variables in `api_key` and `api_secret` with the values obtained from the Partners Panel. These should be set as the default values for the `config` variables. + This table includes the top-level keys and their subkeys, along with their properties, descriptions, formats, default values, environment variables. -| Field | Documentation | Format | Default Value | Environment Variable | -|-----------------------------|--------------------------|-------------|--------------------------------|-------------------------------------| -| **enable_cors** | cors toggle | Boolean | true | ENABLE_CORS | -| **env** | node env | String | development | NODE_ENV | -| **environment** | env | String | fynd | ENV | -| **mongo.host.uri** | host mongo | mongo-uri | mongodb://localhost:27017/ga4 | MONGO_GA4_READ_WRITE | -| **mongo.host.options.appname** | mongo app name | String | ga4 | K8S_POD_NAME | -| **redis.host** | Redis URL of host. | String | redis://localhost:6379/0 | REDIS_EXTENSIONS_READ_WRITE | -| **sentry.dsn** | sentry url | String | | SENTRY_DSN | -| **sentry.environment** | sentry environment | String | development | SENTRY_ENVIRONMENT | -| **newrelic.app_name** | new relic app name | String | ga4 | NEW_RELIC_APP_NAME | -| **newrelic.license_key** | new relic license key | String | | NEW_RELIC_LICENSE_KEY | -| **port** | The port to bind | port | 5050 | PORT | -| **log_level** | log level for logger | String | info | LOG_LEVEL | -| **mode** | app mode | String | server | MODE | -| **API_KEY** | Partners API Key | String | | API_KEY | -| **API_SECRET** | Partners API Secret | String | | API_SECRET | | -| **BROWSER_CONFIG.HOST_MAIN_URL** | Host Main URL | String | | GA4_MAIN_DOMAIN | -| **cluster_url** | Fynd Platform Domain | String | https://api.fynd.com | EXTENSION_CLUSTER_URL | - - ```javascript - extension: { - api_key: { - doc: 'extension api key', - default: 'Your API Key', - env: 'EXTENSION_API_KEY', - }, - api_secret: { - doc: 'extension api secret', - default: 'Your API Secret', - env: 'EXTENSION_API_SECRET', - }, - }, - ``` +| Field | Documentation | Format | Default Value | Environment Variable | +| -------------------------------- | --------------------- | --------- | ----------------------------- | --------------------------- | --- | +| **enable_cors** | cors toggle | Boolean | true | ENABLE_CORS | +| **env** | node env | String | development | NODE_ENV | +| **environment** | env | String | fynd | ENV | +| **mongo.host.uri** | host mongo | mongo-uri | mongodb://localhost:27017/ga4 | MONGO_GA4_READ_WRITE | +| **mongo.host.options.appname** | mongo app name | String | ga4 | K8S_POD_NAME | +| **redis.host** | Redis URL of host. | String | redis://localhost:6379/0 | REDIS_EXTENSIONS_READ_WRITE | +| **sentry.dsn** | sentry url | String | | SENTRY_DSN | +| **sentry.environment** | sentry environment | String | development | SENTRY_ENVIRONMENT | +| **newrelic.app_name** | new relic app name | String | ga4 | NEW_RELIC_APP_NAME | +| **newrelic.license_key** | new relic license key | String | | NEW_RELIC_LICENSE_KEY | +| **port** | The port to bind | port | 5050 | PORT | +| **log_level** | log level for logger | String | info | LOG_LEVEL | +| **mode** | app mode | String | server | MODE | +| **API_KEY** | Partners API Key | String | | API_KEY | +| **API_SECRET** | Partners API Secret | String | | API_SECRET | | +| **BROWSER_CONFIG.HOST_MAIN_URL** | Host Main URL | String | | GA4_MAIN_DOMAIN | +| **cluster_url** | Fynd Platform Domain | String | https://api.fynd.com | EXTENSION_CLUSTER_URL | + +```javascript +api_key: { + doc: 'extension api key', + default: 'Your API Key', + env: 'EXTENSION_API_KEY', +}, +api_secret: { + doc: 'extension api secret', + default: 'Your API Secret', + env: 'EXTENSION_API_SECRET', +}, +``` 8. πŸ–₯️ Also update MongoDB and Redis Environment Variables according to your machine. @@ -235,21 +230,20 @@ You have successfully set up your payment extension on the Fynd platform. ```bash ngrok http 3000 ``` + Replace `3000` with the actual port number your server is using. This will generate a public URL that securely tunnels to your local server. -11. 🌐 Update default env value for `GA4_MAIN_DOMAIN` with this URL in `BROWSER_CONFIG.HOST_MAIN_URL`. - - ```javascript - BROWSER_CONFIG: { - HOST_MAIN_URL: { - doc: 'Host Main URL', - format: String, - default: 'https://your-ngrok-url', - env: 'GA4_MAIN_DOMAIN', - arg: 'ga4_main_domain', - }, - }, - ``` +11. 🌐 Update default env value for `EXTENSION_BASE_URL` with this URL. + +```javascript +base_url: { + doc: 'Host Main URL', + format: String, + default: 'https://your-ngrok-url', + env: 'GA4_MAIN_DOMAIN', + arg: 'ga4_main_domain', +}, +``` 12. πŸ› οΈ Navigate to your extension in the Partner Panel and update the Extension URL field with the generated ngrok URL. @@ -261,7 +255,6 @@ You have successfully set up your payment extension on the Fynd platform. 14. πŸŽ‰ You are ready to go. - ### πŸ§ͺ Running Test Cases After you have completed the local setup, you can run the test cases to ensure everything is working as expected. Follow these steps to execute the tests: @@ -270,84 +263,17 @@ After you have completed the local setup, you can run the test cases to ensure e If you're not already there, switch to your project's root directory in your terminal. - ```bash - cd path/to/your/project - ``` + ```bash + cd path/to/your/project + ``` 2. **πŸ§ͺ Run Backend Tests.** Execute the backend test cases using the following command: - ```bash - npm test - ``` - - -### πŸ” Newrelic Integration (Optional) - -The Google Analytics Extension (GA4) comes pre-configured for integration with New Relic, allowing you to monitor your application's performance in real-time. This feature provides insights to help you improve and optimize your extension efficiently. - -To leverage New Relic for performance monitoring, update the default values for the following environment variables in the app/fdk/config.js file in your project directory. This step ensures the New Relic integration is securely configured with your specific credentials. - -1. `NEW_RELIC_APP_NAME`: Set this to the name you wish your application to appear as in New Relic. It helps easily identify your project within the New Relic dashboard. -2. `NEW_RELIC_LICENSE_KEY`: This is your unique New Relic license key, which authorizes the New Relic agent to send monitoring data to your New Relic account. - - ```javascript - newrelic: { - app_name: { - doc: 'new relic app name', - format: String, - default: '', - env: 'NEW_RELIC_APP_NAME', - arg: 'new_relic_app_name', - }, - license_key: { - doc: 'new relic license key', - format: String, - default: '', - env: 'NEW_RELIC_LICENSE_KEY', - args: 'new_relic_license_key', - }, - }, - ``` - -By updating these variables, you can activate New Relic's data collection, offering a comprehensive view of your application's performance. - -> **Notes :** -To remove New Relic integration completely, delete the New Relic environment variables in your `app/fdk/config.js` file and uninstall the New Relic package with `npm uninstall newrelic`. Remove `require('./connections/newrelic');` from `app/index.js`. Delete the `app/connections/newrelic.js` and `newrelic.js` files and update your documentation accordingly. - -### 🚨 Sentry Integration (Optional) - -Similar to New Relic, the Google Analytics Extension (GA4) comes pre-configured for optional integration with Sentry. Sentry provides real-time error tracking and monitoring, offering insights to quickly identify, diagnose, and fix issues, thereby enhancing your extension's reliability and user experience. - -To enable Sentry for error monitoring, update the environment variables in the `app/fdk/config.js` file with your Sentry credentials: - -1. `SENTRY_DSN`: This is the unique Data Source Name (DSN) provided by Sentry, which directs error messages to your Sentry project. -2. `SENTRY_ENVIRONMENT`: Specify the environment your application is running in, such as development, staging, or production. This helps in filtering and categorizing issues within Sentry. - - ```javascript - sentry: { - dsn: { - doc: 'sentry url', - format: String, - default: '', - env: 'SENTRY_DSN', - arg: 'sentry_dsn', - }, - environment: { - doc: 'sentry environment', - format: String, - default: 'development', - env: 'SENTRY_ENVIRONMENT', - arg: 'sentry_environment', - }, - }, - ``` - -Configuring these variables enables Sentry's error tracking for your application, offering a layer of insight into its stability and helping you maintain a high-quality user experience. - -> **Notes :** -To remove Sentry integration, delete the Sentry environment variables in your `app/fdk/config.js` file and uninstall the Sentry package with `npm uninstall @sentry/node`. Remove `require('./connections/sentry');` from `app/index.js`. Delete the `app/connections/sentry.js` and `sentry.js` files and update your documentation accordingly. + ```bash + npm test + ``` ### πŸ“‹ Fynd Platform Panel @@ -377,12 +303,3 @@ This project enforces code quality and consistency using ESLint and Prettier. Be ### How It Works Merchants can easily install and activate the payment extension on their Fynd Platform. During checkout, customers will be presented with the payment options provided by the extension. Currently, the Fynd Platform supports standard checkout, where customers are redirected to the payment gateway's hosted page to complete their transactions. - - - -## Security and Best Practices - -- **Verifying API Calls:** Use checksums generated with your Extension API Secret to secure communications between the Fynd Platform and your payment extension. -- **Idempotency:** Ensure your extension supports idempotency to prevent duplicate transactions and ensure a consistent buyer experience. - -For more detailed examples and additional languages, refer to the provided guides.