Business API Design Specification - `Create Refundrequest`

A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic.

While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized.

This document provides an in-depth explanation of the architectural design of the createRefundRequest Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side.

Main Data Object and CRUD Operation

The createRefundRequest Business API is designed to handle a create operation on the RefundRequest data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow.

API Description

Student files refund request for a completed enrollment only after first lesson and only if no additional lessons are complete. Auto-approves, updates enrollment statuses, and triggers Stripe refund if eligible.

API Frontend Description By The Backend Architect

Students can trigger a refund for their enrollment only after first lesson, provided no additional lessons have been completed. The refund is auto-approved and reflected in both user’s and admin’s views; tutor and admin are notified. No manual approval or asynchronous queue, strictly within narrow business criteria.

API Options

Auto Params : true Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to false if you want to define all input parameters manually.
Raise Api Event : true Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the refundrequest-created Kafka Topic Note that the DB-Level events for create, update and delete operations will always be raised for internal reasons.
Active Check : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the ApiCheckOption to determine whether this is checked during the query or after fetching the instance.
Read From Entity Cache : false If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records.

API Controllers

A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel.

REST Controller

The createRefundRequest Business API includes a REST controller that can be triggered via the following route:

/v1/refundrequests

By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the Parameters section.

MCP Tool

REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This createRefundRequest Business API will be registered as a tool on the MCP server within the service binding.

API Parameters

The createRefundRequest Business API has 9 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client.

Business API parameters can be:

Auto-generated by Mindbricks — inferred from the CRUD type and the property definitions of the main data object when the autoParameters option is enabled.
Custom parameters added by the architect — these can supplement or override the auto-generated parameters.

Regular Parameters

Name	Type	Required	Default	Location	Data Path

`refundRequestId`	`ID`	`No`	`-`	`body`	`refundRequestId`
Description:	This id paremeter is used to create the data object with a given specific id. Leave null for automatic id.

`enrollmentId`	`ID`	`Yes`	`-`	`body`	`enrollmentId`
Description:	FK to enrollment object for which refund is being requested (unique: one refund per enrollment).

`requestedBy`	`ID`	`Yes`	`-`	`session`	`userId`
Description:	User (student) making the refund request (auth:user id).

`requestedAt`	`Date`	`Yes`	`-`	`body`	`requestedAt`
Description:	Datetime refund was requested.

`processedAt`	`Date`	`No`	`-`	`body`	`processedAt`
Description:	When refund was processed by system (auto-approval).

`status`	`Enum`	`Yes`	`-`	`body`	`status`
Description:	Refund status: pending, approved, rejected, autoApproved (system processed/approved instantly).

`reason`	`String`	`Yes`	`-`	`body`	`reason`
Description:	User-supplied reason for requesting refund.

`firstLessonCompleted`	`Boolean`	`Yes`	`-`	`body`	`firstLessonCompleted`
Description:	True if this refund is after first lesson (enforced by workflow); must be checked before approval.

`adminNote`	`String`	`No`	`-`	`body`	`adminNote`
Description:	Admin note explaining the refund decision (approve/reject reason).

Parameter Transformations

Some parameters are post-processed using transform scripts after being read from the request but before validation or workflow execution. Only parameters with a transform script are listed below.

No parameters are transformed in this API.

AUTH Configuration

The authentication and authorization configuration defines the core access rules for the createRefundRequest Business API. These checks are applied after parameter validation and before executing the main business logic.

While these settings cover the most common scenarios, more fine-grained or conditional access control—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like PermissionCheckAction, MembershipCheckAction, or ObjectPermissionCheckAction.

This API requires login (loginRequired = true). Requests from non-logged-in users will return a 401 Unauthorized error. Login is necessary but not sufficient, as additional role, permission, or other authorization checks may still apply.

Ownership Checks

Role and Permission Settings

Absolute roles (bypass all auth checks):
Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks:
[user, student, admin, superAdmin]

Data Clause

Defines custom field-value assignments used to modify or augment the default payload for create and update operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings.

Custom Data Clause Override No custom data clause override configured

Actual Data Clause

The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager.

{
  id: this.refundRequestId,
  enrollmentId: this.enrollmentId,
  requestedBy: this.requestedBy,
  requestedAt: this.requestedAt,
  processedAt: this.processedAt,
  status: this.status,
  reason: this.reason,
  firstLessonCompleted: this.firstLessonCompleted,
  adminNote: this.adminNote,
  isActive: true,
  _archivedAt: null,
}

Business Logic Workflow

[1] Step : startBusinessApi

Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution.

You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `sseSettings`, `cronSettings`

[2] Step : readParameters

Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context.

You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters`

[3] Step : transposeParameters

Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing.

[4] Step : checkParameters

Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails.

[5] Action : fetchEnrollment

Action Type: FetchObjectAction

Fetch the enrollment record to validate payment status and refund eligibility

class Api {
  async fetchEnrollment() {
    // Fetch Object on childObject enrollment

    const userQuery = {
      $and: [
        {
          id: runMScript(() => this.enrollmentId, {
            path: "services[3].businessLogic[3].actions.fetchObjectActions[0].matchValue",
          }),
        },
        { isActive: true },
      ],
    };
    const { convertUserQueryToSequelizeQuery } = require("common");
    const scriptQuery = convertUserQueryToSequelizeQuery(userQuery);

    // get object from db
    const data = await getEnrollmentByQuery(scriptQuery);

    if (!data) {
      throw new NotFoundError("errMsg_FethcedObjectNotFound:enrollment");
    }

    return data;
  }
}

[6] Action : fetchPaymentRecord

Action Type: FetchObjectAction

Fetch the Stripe payment record to get paymentId for refund

class Api {
  async fetchPaymentRecord() {
    // Fetch Object on childObject sys_enrollmentPayment

    const userQuery = {
      $and: [
        {
          orderId: runMScript(() => this.enrollmentId, {
            path: "services[3].businessLogic[3].actions.fetchObjectActions[1].matchValue",
          }),
        },
        { isActive: true },
      ],
    };
    const { convertUserQueryToSequelizeQuery } = require("common");
    const scriptQuery = convertUserQueryToSequelizeQuery(userQuery);

    // get object from db
    const data = await getSys_enrollmentPaymentByQuery(scriptQuery);

    if (!data) {
      throw new NotFoundError(
        "errMsg_FethcedObjectNotFound:sys_enrollmentPayment",
      );
    }

    return data;
  }
}

[7] Action : fetchLessonSlots

Action Type: FetchObjectAction

Fetch all lesson slots for this enrollment to check completion status

class Api {
  async fetchLessonSlots() {
    // Fetch Object on childObject lessonSlot

    const userQuery = {
      $and: [
        runMScript(
          () => ({ id: { $in: this.fetchedEnrollment.lessonSlotIds } }),
          {
            path: "services[3].businessLogic[3].actions.fetchObjectActions[2].whereClause",
          },
        ),
        { isActive: true },
      ],
    };
    const { convertUserQueryToElasticQuery } = require("common");
    const scriptQuery = convertUserQueryToElasticQuery(userQuery);

    // get object list from elasticsearch index
    const elasticIndex = new ElasticIndexer("lessonSlot");
    const dataList =
      (await elasticIndex.getDataByPage(0, 500, scriptQuery)) ?? [];

    return dataList;
  }
}

[8] Action : runRefundValidation

Action Type: FunctionCallAction

Validate refund eligibility based on enrollment status, payment, and lesson completion

class Api {
  async runRefundValidation() {
    try {
      return runMScript(
        () =>
          LIB.validateRefundEligibility(
            this.fetchedEnrollment,
            this.enrollmentLessonSlots,
            this.paymentRecord,
          ),
        {
          path: "services[3].businessLogic[3].actions.functionCallActions[0].callScript",
        },
      );
    } catch (err) {
      console.error("Error in FunctionCallAction runRefundValidation:", err);
      throw err;
    }
  }
}

[9] Action : enforceRefundEligibility

Action Type: ValidationAction

Block refund if eligibility validation fails

class Api {
  async enforceRefundEligibility() {
    const isValid = runMScript(
      () => this.refundValidation && this.refundValidation.eligible === true,
      {
        path: "services[3].businessLogic[3].actions.validationActions[0].validationScript",
      },
    );

    if (!isValid) {
      throw new BadRequestError(
        "Refund not eligible. Please check the refund policy requirements.",
      );
    }
    return isValid;
  }
}

[10] Action : setRefundFields

Action Type: AddToContextAction

Set auto-computed fields: autoApproved gets instant processing, pendingReview gets pending status

class Api {
  async setRefundFields() {
    try {
      this["firstLessonCompleted"] = runMScript(
        () => this.refundValidation.firstLessonCompleted || false,
        {
          path: "services[3].businessLogic[3].actions.addToContextActions[0].context[0].contextValue",
        },
      );

      this["status"] = runMScript(
        () =>
          this.refundValidation.refundType === "autoApproved"
            ? "autoApproved"
            : "pending",
        {
          path: "services[3].businessLogic[3].actions.addToContextActions[0].context[1].contextValue",
        },
      );

      this["processedAt"] = runMScript(
        () =>
          this.refundValidation.refundType === "autoApproved"
            ? new Date()
            : null,
        {
          path: "services[3].businessLogic[3].actions.addToContextActions[0].context[2].contextValue",
        },
      );

      this["requestedAt"] = runMScript(() => new Date(), {
        path: "services[3].businessLogic[3].actions.addToContextActions[0].context[3].contextValue",
      });

      return true;
    } catch (error) {
      console.error("AddToContextAction error:", error);
      throw error;
    }
  }
}

[11] Step : checkBasicAuth

Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions.

You can use the following settings to change some behavior of this step. `authOptions`

[12] Step : buildDataClause

Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency.

You can use the following settings to change some behavior of this step. `dataClause`

[13] Step : mainCreateOperation

Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records.

[14] Action : stripeCreateRefund

Action Type: IntegrationAction

Process the actual Stripe refund — only for auto-approved refunds

class Api {
  async stripeCreateRefund() {
    // Integration Action for stripe

    const input = {
      paymentIntent: runMScript(
        () => this.refundValidation.stripePaymentIntentId,
        {
          path: "services[3].businessLogic[3].actions.integrationActions[0].parameters[0].parameterValue",
        },
      ),
      reason: runMScript(() => "requested_by_customer", {
        path: "services[3].businessLogic[3].actions.integrationActions[0].parameters[1].parameterValue",
      }),
    };

    const stripeClient = await getIntegrationClient("stripe");
    return await stripeClient.createRefund(input);
  }
}

[15] Action : updateEnrollmentRefundStatus

Action Type: UpdateCrudAction

Mark the enrollment as refunded — only for auto-approved refunds

class Api {
  async updateEnrollmentRefundStatus() {
    // Aggregated Update Operation on childObject enrollment

    const params = {
      refundStatus: runMScript(() => "processed", {
        path: "services[3].businessLogic[3].actions.updateCrudActions[0].dataClause[0].dataValue",
      }),
      paymentStatus: runMScript(() => "refunded", {
        path: "services[3].businessLogic[3].actions.updateCrudActions[0].dataClause[1].dataValue",
      }),
      enrollmentStatus: runMScript(() => "canceled", {
        path: "services[3].businessLogic[3].actions.updateCrudActions[0].dataClause[2].dataValue",
      }),
    };
    const userQuery = runMScript(() => ({ id: this.enrollmentId }), {
      path: "services[3].businessLogic[3].actions.updateCrudActions[0].whereClause",
    });

    const { convertUserQueryToSequelizeQuery } = require("common");
    const query = convertUserQueryToSequelizeQuery(userQuery);

    const result = await updateEnrollmentByQuery(params, query, this);
    if (!result) return null;

    const resultArray = Array.isArray(result) ? result : [result];
    // if updated record is in main data update main data
    if (this.dbResult) {
      for (const item of resultArray) {
        if (item.id == this.dbResult.id) {
          Object.assign(this.dbResult, item);
          this.refundRequest = this.dbResult;
        }
      }
    }
    if (resultArray.length == 0) return null;
    if (resultArray.length == 1) return resultArray[0];
    return resultArray;
  }
}

[16] Action : freeLessonSlots

Action Type: FunctionCallAction

Cancel lesson slots when refund is auto-approved

class Api {
  async freeLessonSlots() {
    try {
      return await runMScript(
        () =>
          (async () =>
            await LIB.cancelEnrollmentLessonSlots(
              this.fetchedEnrollment.lessonSlotIds,
              this.session,
            ))(),
        {
          path: "services[3].businessLogic[3].actions.functionCallActions[1].callScript",
        },
      );
    } catch (err) {
      console.error("Error in FunctionCallAction freeLessonSlots:", err);
      throw err;
    }
  }
}

[17] Step : buildOutput

Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract.

[18] Step : sendResponse

Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state.

[19] Step : raiseApiEvent

Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step.

Rest Usage

Rest Client Parameters

Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources.

The createRefundRequest api has got 7 regular client parameters

Parameter	Type	Required	Population
enrollmentId	ID	true	request.body?.[“enrollmentId”]
requestedAt	Date	true	request.body?.[“requestedAt”]
processedAt	Date	false	request.body?.[“processedAt”]
status	Enum	true	request.body?.[“status”]
reason	String	true	request.body?.[“reason”]
firstLessonCompleted	Boolean	true	request.body?.[“firstLessonCompleted”]
adminNote	String	false	request.body?.[“adminNote”]

REST Request

To access the api you can use the REST controller with the path POST /v1/refundrequests

  axios({
    method: 'POST',
    url: '/v1/refundrequests',
    data: {
            enrollmentId:"ID",  
            requestedAt:"Date",  
            processedAt:"Date",  
            status:"Enum",  
            reason:"String",  
            firstLessonCompleted:"Boolean",  
            adminNote:"String",  
    
    },
    params: {
    
        }
  });

REST Response

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. For error handling, refer to the “Error Response” section.

Following JSON represents the most comprehensive form of the refundRequest object in the respones. However, some properties may be omitted based on the object’s internal logic.

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "refundRequest",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"refundRequest": {
		"id": "ID",
		"enrollmentId": "ID",
		"requestedBy": "ID",
		"requestedAt": "Date",
		"processedAt": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"reason": "String",
		"firstLessonCompleted": "Boolean",
		"adminNote": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Business API Design Specification - Create Refundrequest

Main Data Object and CRUD Operation

API Description

API Frontend Description By The Backend Architect

API Options

API Controllers

REST Controller

MCP Tool

API Parameters

Regular Parameters

Parameter Transformations

AUTH Configuration

Login Requirement

Ownership Checks

Role and Permission Settings

Data Clause

Business Logic Workflow

[1] Step : startBusinessApi

You can use the following settings to change some behavior of this step. apiOptions, restSettings, grpcSettings, kafkaSettings, sseSettings, cronSettings

[2] Step : readParameters

You can use the following settings to change some behavior of this step. customParameters, redisParameters

[3] Step : transposeParameters

[4] Step : checkParameters

[5] Action : fetchEnrollment

[6] Action : fetchPaymentRecord

[7] Action : fetchLessonSlots

[8] Action : runRefundValidation

[9] Action : enforceRefundEligibility

[10] Action : setRefundFields

[11] Step : checkBasicAuth

You can use the following settings to change some behavior of this step. authOptions

[12] Step : buildDataClause

You can use the following settings to change some behavior of this step. dataClause

[13] Step : mainCreateOperation

[14] Action : stripeCreateRefund

[15] Action : updateEnrollmentRefundStatus

[16] Action : freeLessonSlots

[17] Step : buildOutput

[18] Step : sendResponse

[19] Step : raiseApiEvent

Rest Usage

Rest Client Parameters

REST Request

REST Response

Business API Design Specification - `Create Refundrequest`

You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `sseSettings`, `cronSettings`

You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters`

You can use the following settings to change some behavior of this step. `authOptions`

You can use the following settings to change some behavior of this step. `dataClause`