Boilerplate Overview

A Boilerplate is a pre-written codebase that speeds development by providing a foundational template for building extensions. Fynd provides a boilerplate that simplifies the development process. This template includes pre-implemented OAuth functionality, necessary API endpoints, and a frontend interface where sellers can enter PG credentials. It is an enhanced version of the General Extension boilerplate with additional configuration to support payment-specific features. Developers should first familiarize themselves with the General Extension boilerplate before working on the Payments boilerplate.

Prerequisite

Download the Payments Boilerplate code from Here.

├── app
│   ├── __tests__
│   │     ├── creds.spec.js
│   │     ├── encrypt.spec.js
│   │     ├── orderController.spec.js
│   │     └── signature.spec.js
│   │
│   ├── controllers
│   │     ├── creds.controller.js
│   │     ├── fp-payment.controller.js
│   │     └── pg-webhook.controller.js
│   │
│   ├── middleware
│   │     ├── checksum.middleware.js
│   │     └── error.middleware.js
│   │
│   ├── models
│   │     ├── creds.model.js
│   │     └── payment.model.js
│   │
│   ├── routes
│   │     └── creds.router.js
│   │
│   ├── services
│   │     ├── creds.service.js
│   │     └── payment.service.js
│   │
│   ├── utils
│   │     ├── encrypt.util.js
│   │     ├── error.util.js
│   │     └── signature.util.js
│   │
│   ├── fdk.js
│   └── server.js
│
├── .github/
├── frontend/
├── .dockerignore
├── .env.example
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── fdk.ext.config.json
├── index.js
├── jest.config.js
├── LICENSE
├── package-lock.json
├── package.json
└── README.md

The files described below are specific to the Payments Extension. Since the Payments Extension boilerplate is built on the General Extension boilerplate, commonly shared files from the General Extension Boilerplate are not included in the list below.

Go through the General Extension boilerplate for foundational understanding.

The file naming and structure in the boilerplate primarily follow Fynd’s standard conventions. However, some files adhere to custom conventions that are not documented. The boilerplate files are divided into the following categories:

app/__tests__

It contains unit test files to validate the core functionalities of the payment extension.

• creds.spec.js: Validates credential management, ensuring secure handling of API keys and authentication data.
• encrypt.spec.js: Tests encryption utilities to verify secure data encoding and decoding.
• signature.spec.js: Verifies the signature generation and validation process for secure communication.
• orderController.js: This file is a test suite. It verifies the functionality of various payment-related handlers, including initiating payments, creating refunds, fetching payment/refund details, handling callbacks, and processing webhooks. The tests ensure each handler responds correctly to valid inputs and handles errors gracefully for invalid or missing data.

app/controllers

These controllers facilitate the application’s core functionalities by processing incoming API requests, interacting with services or models, and returning appropriate responses. This directory contains the following files:

• creds.controller.js: Manages operations related to credentials and status mapping, handling API requests for credential management and status updates.
• fp-payment.controller.js: This file handles the logic for managing payments and refunds. It includes handlers to initiate payments, create refunds, and fetch payment or refund details. It interacts with a local database to store transaction data and prepares responses expected by the Fynd Commerce platform.
• pg-webhook.controller.js: This file implements handlers for processing payment and refund callbacks and webhooks in the Fynd Payments extension. It verifies payloads, updates payment/refund sessions on the Fynd platform, and handles status updates like complete, pending, or failed. It also includes logic for checksum validation (mocked) and integrates with platform clients using the FDK SDK. The handlers ensure that real-time status updates from payment gateways are correctly reflected in the platform.

app/middleware

It helps in building a secure and reliable payment extension by addressing error handling and data integrity concerns effectively.

• checksum.middleware.js: This file defines middleware functions to verify incoming requests in the Payments extension.
• error.middleware.js: This file defines a global error-handling middleware for the Payments extension. It logs any encountered error and sends response with an appropriate status code and error message. If no specific error details are provided, it defaults to a 500 Internal Server Error.

app/models/

This file manages database schema definitions and serves as the central place to define and organize the data models used throughout the application.

• creds.model.js: This file defines a utility for securely storing, retrieving, and checking encrypted credentials in the Payments extension using FDK’s built-in extension storage.
• payment.model.js: This file defines PaymentModel, a temporary in-memory storage utility for storing and retrieving payment and refund data using FDK’s extension storage.

app/routes

These files collectively define the routing logic for various functionalities within the payment extension, ensuring organized and efficient API endpoint management. The app/routes directory contains two files:

• creds.router.js: Manages routes related to credentials and status mapper APIs.

app/services

• creds.service.js: This file sets up an Express route to check if payment credentials are configured for a given app.
• payment.service.js: This file registers core payment and refund API routes for the Payments extension.

app/utils

It contains various utility modules that provide helper functions to support the main payment processing logic. Here’s an overview of each component:

• encrypt.util.js: It provides functions for encryption, decryption, or hashing operations.
• error.util.js: It contains utility functions related to error handling.
• signature.util.js: It contains functions related to generating and verifying digital signatures.

fdk.js

This file initializes the FDK extension setup using the @gofynd/fdk-extension-javascript SDK. It configures a SQLite-based storage for development purposes and sets up the extension with API credentials, base URL, and lifecycle callbacks like OAuth and uninstall.

server.js

It sets up the Express.js application, configuring middleware for cookie parsing, JSON body parsing, and serving static files. It integrates the FDK extension handler and defines routing for order processing and credential management APIs.