Payment Framework Generated Assets

The payment framework is not a separate service in Mindbricks. Instead, when you enable the StripeOrder pattern for any data object in any service, Mindbricks automatically adds payment infrastructure to that service. This includes automatic data objects, Business APIs, system routes, Kafka event topics, and a demo frontend.

Activation: The payment framework is activated when objectIsAnOrderObject is set to true in the StripeOrder pattern configuration for a data object.

Automatic Payment Data Objects

When StripeOrder is enabled for a data object (e.g., order, ticket, reservation), Mindbricks automatically generates three system data objects in the same service:

1. sys_{objectName}Payment Data Object

A payment storage object that tracks the payment lifecycle for each order instance.

Naming Convention:

• Data Object Name: sys_{objectName}Payment (e.g., sys_orderPayment, sys_ticketPayment)
• Model Name: Sys{ObjectName}Payment (PascalCase, e.g., SysOrderPayment, SysTicketPayment)
• Service Reference: {serviceName}:sys_{objectName}Payment

System-Owned Properties:

Authorization:

• dataObjectAccess: "accessPrivate" — Only accessible by the owner or admins
• objectDataIsInTenantLevel: true — Tenant-scoped when multi-tenancy is active

Note: This object is automatically created for each data object that has StripeOrder enabled. The orderId property references the ID of the source order object.

2. sys_paymentCustomer Data Object

A payment storage object that stores Stripe customer information for users.

Naming Convention:

• Data Object Name: sys_paymentCustomer
• Model Name: SysPaymentCustomer (PascalCase)
• Service Reference: {serviceName}:sys_paymentCustomer

System-Owned Properties:

Authorization:

• dataObjectAccess: "accessPrivate" — Only accessible by the owner or admins
• objectDataIsInTenantLevel: true — Tenant-scoped when multi-tenancy is active

Note: This object is created once per service (not per order object). It stores the Stripe customer ID for each user, which is reused across all payment operations.

3. sys_paymentMethod Data Object

A payment storage object that stores saved payment methods (credit cards) for users.

Naming Convention:

• Data Object Name: sys_paymentMethod
• Model Name: SysPaymentMethod (PascalCase)
• Service Reference: {serviceName}:sys_paymentMethod

System-Owned Properties:

Authorization:

• dataObjectAccess: "accessPrivate" — Only accessible by the owner or admins
• objectDataIsInTenantLevel: true — Tenant-scoped when multi-tenancy is active

Note: This object is created once per service (not per order object). Users can save multiple payment methods, and these are reused across all payment operations.

Automatic Business APIs and REST Routes

Mindbricks automatically generates Business APIs for the payment data objects. The REST routes follow standard naming conventions based on the API name and crudType.

Payment Data Object APIs (per order object)

For each order object with StripeOrder enabled, the following Business APIs are generated:

Examples:

• For order object: getOrderPayment, getOrderPaymentByOrderId, createOrderPayment, etc.
• For ticket object: getTicketPayment, getTicketPaymentByOrderId, createTicketPayment, etc.

Note: Replace {ObjectName} with the PascalCase model name (e.g., Order, Ticket, Reservation).

Payment Customer Data Object APIs

Payment Method Data Object APIs

Note: Payment methods are typically managed through system routes (see below) rather than standard Business APIs.

Automatic System Routes

Mindbricks automatically generates system routes for payment operations. These routes are not versioned and are mounted directly to the service API base path.

Payment Methods Management Routes

These routes are mounted at /{serviceName}-api/payment-methods/:

Request Body (/add):

{
  "paymentMethodId": "pm_1SQw5aP5uUv56CseDGzT1dzP"
}

Response (/list):

[
  {
    "id": "19a5fbfd-3c25-405b-a7f7-06f023f2ca01",
    "paymentMethodId": "pm_1SQv9CP5uUv56Cse5BQ3nGW8",
    "userId": "f7103b85-fcda-4dec-92c6-c336f71fd3a2",
    "customerId": "cus_TNgWUw5QkmUPLa",
    "cardHolderName": "John Doe",
    "cardHolderZip": "34662",
    "platform": "stripe",
    "cardInfo": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 11,
      "exp_year": 2033
    }
  }
]

Stripe Demo Frontend Routes

For each order object with StripeOrder enabled, Mindbricks generates demo frontend routes for testing and demonstration purposes.

Examples:

• For order object: /{serviceName}-api/stripe-demo/order
• For ticket object: /{serviceName}-api/stripe-demo/ticket

Note: The demo frontend is automatically generated and includes a complete payment flow UI. It can be customized by modifying files in the stripe-demo/{objectName}/ directory.

Payment Status Change Edge Functions

When edgeFunctionOnStatusChange is specified in the StripeOrderConfig, Mindbricks automatically creates a Kafka edge controller that triggers the specified edge function after any payment status change.

Configuration:

{
  "stripeOrder": {
    "objectIsAnOrderObject": true,
    "configuration": {
      "edgeFunctionOnStatusChange": "handlePaymentStatusChange"
    }
  }
}

Trigger Events:

• Payment started
• Payment completed (succeeded)
• Payment canceled
• Payment failed

Edge Function Request:

• Trigger: Kafka message from payment status change event
• Session: Automatically attached when user is logged in
• Request Data: The latest order object is directly accessible on the request:
  • request.{objectName} (e.g., request.order, request.ticket, request.reservation)
  • Includes all order data with updated payment status

Example Edge Function:

module.exports = async (request) => {
  const order = request.order; // or request.ticket, request.reservation, etc.
  
  if (order.paymentStatus === "succeeded") {
    // Execute business logic after successful payment
    // e.g., send confirmation email, update inventory, etc.
  }
  
  return { status: 200, message: "Payment status change processed" };
};

Note: This edge function does not require a separate edge controller definition. The Kafka edge controller is automatically built in the background.

Generated Kafka Topics

Payment Lifecycle Event Topics

For each order object with StripeOrder enabled, Mindbricks automatically generates Kafka event topics for payment lifecycle operations. These events are published when the corresponding payment Business APIs are called.

Examples: If project code name is myproject, service is order, and object is order:

• myproject-order-service-orderpayment-started
• myproject-order-service-orderpayment-refreshed
• myproject-order-service-orderpayment-calledback

Note:

• Replace {projectCodeName} with your actual project code name
• Replace {serviceName} with the actual service name where the payment framework is enabled
• Replace {objectName} with the lowercase object name (e.g., order, ticket, reservation)
• These topics are automatically created when StripeOrder is enabled

Payment Status Change Events (Edge Function)

When edgeFunctionOnStatusChange is specified in the StripeOrderConfig, Mindbricks automatically creates a Kafka edge controller that listens to payment status change events and triggers the specified edge function.

Edge Controller Configuration:

• Trigger: Kafka messages from payment status change events
• Request Topic: Automatically configured to listen to payment-related events
• Session: Automatically attached when user is logged in
• Request Data: The latest order object is directly accessible on the request (e.g., request.order, request.ticket)

Note: The exact Kafka topic name is automatically configured by Mindbricks. The edge function receives the order object data with updated payment status, allowing custom business logic to execute after payment events (completed, canceled, failed).

Database Event Topics

For each payment data object, standard database event topics are generated:

sys_{objectName}Payment Data Object Topics

sys_paymentCustomer Data Object Topics

sys_paymentMethod Data Object Topics

Database Utility Functions

For each payment data object, Mindbricks generates database utility functions in the dbLayer module following the standard naming convention.

Payment Data Object Functions (per order object)

const {
  createSys{ObjectName}Payment,
  createBulkSys{ObjectName}Payment,
  getSys{ObjectName}PaymentById,
  getSys{ObjectName}PaymentAggById,
  getSys{ObjectName}PaymentListByQuery,
  getSys{ObjectName}PaymentByQuery,
  getSys{ObjectName}PaymentStatsByQuery,
  getIdListOfSys{ObjectName}PaymentByField,
  updateSys{ObjectName}PaymentById,
  updateSys{ObjectName}PaymentByIdList,
  updateSys{ObjectName}PaymentByQuery,
  deleteSys{ObjectName}PaymentById,
  deleteSys{ObjectName}PaymentByQuery
} = require("dbLayer");

Examples:

• For order object: createSysOrderPayment, getSysOrderPaymentById, etc.
• For ticket object: createSysTicketPayment, getSysTicketPaymentById, etc.

Payment Customer Data Object Functions

const {
  createSysPaymentCustomer,
  createBulkSysPaymentCustomer,
  getSysPaymentCustomerById,
  getSysPaymentCustomerAggById,
  getSysPaymentCustomerListByQuery,
  getSysPaymentCustomerByQuery,
  getSysPaymentCustomerStatsByQuery,
  getIdListOfSysPaymentCustomerByField,
  updateSysPaymentCustomerById,
  updateSysPaymentCustomerByIdList,
  updateSysPaymentCustomerByQuery,
  deleteSysPaymentCustomerById,
  deleteSysPaymentCustomerByQuery
} = require("dbLayer");

Payment Method Data Object Functions

const {
  createSysPaymentMethod,
  createBulkSysPaymentMethod,
  getSysPaymentMethodById,
  getSysPaymentMethodAggById,
  getSysPaymentMethodListByQuery,
  getSysPaymentMethodByQuery,
  getSysPaymentMethodStatsByQuery,
  getIdListOfSysPaymentMethodByField,
  updateSysPaymentMethodById,
  updateSysPaymentMethodByIdList,
  updateSysPaymentMethodByQuery,
  deleteSysPaymentMethodById,
  deleteSysPaymentMethodByQuery
} = require("dbLayer");

Note: There are also utility functions available via paymentUtils for payment-specific operations:

• getPaymentCustomerId(session, platform) — Get Stripe customer ID for a user
• savePaymentCustomerId(session, platform) — Create or retrieve Stripe customer ID
• getPaymentMethodsOfUser(session, platform) — Get all payment methods for a user
• addPaymentMethodToCustomer(userId, customerId, paymentMethodId, platform, tenantId) — Add payment method to customer
• deletePaymentMethod(userId, paymentMethodId, platform) — Delete a payment method

For detailed documentation on all database utility functions, see the Database Utility Functions guide.

Payment Business APIs

In addition to the standard CRUD APIs, Mindbricks automatically generates special Business APIs for managing the payment lifecycle. These APIs are generated by the payment framework helper function for each order object with StripeOrder enabled.

start{ObjectName}Payment API

Business API Name: start{ObjectName}Payment (e.g., startOrderPayment, startTicketPayment)

REST Route: /{serviceName}-api/v1/start{objectName}payment/:orderId

HTTP Method: PATCH

Description: Initiates the Stripe payment flow for an order. Creates and confirms a PaymentIntent on Stripe in a single step. This is a Business API that performs an update operation on the order data object.

Path Parameters:

• :orderId — The ID of the order to start payment for

Request Body:

{
  "paymentUserParams": {
    "paymentMethodId": "pm_1234567890",
    "return_url": "https://yourapp.com/payment-result" // optional but recommended
  }
}

Response:

{
  "paymentResult": {
    "success": true,
    "paymentTicketId": "payment-record-uuid",
    "orderId": "order-uuid",
    "paymentId": "pi_1234567890",
    "paymentStatus": "succeeded",
    "paymentIntentInfo": {
      "paymentIntentId": "pi_1234567890",
      "clientSecret": "pi_1234567890_secret_xyz",
      "publicKey": "pk_test_...",
      "status": "succeeded"
    },
    "statusLiteral": "success",
    "amount": 100.00,
    "currency": "USD",
    "description": "Order description"
  }
}

Auth Requirements: Login required, ownership check (user must own the order)

Kafka Event: When this API is called, a Kafka event is published to:

• Topic: {projectCodeName}-{serviceName}-service-{objectName}payment-started
• Example: myproject-order-service-orderpayment-started

Note:

• This API is automatically generated when StripeOrder is enabled
• The API performs both PaymentIntent creation and confirmation in a single step
• In cases requiring 3D Secure or bank authentication, the payment may require frontend completion
• The return_url is strongly recommended to handle payment result pages
• The exact route path follows the standard naming convention: /v1/start{objectName}payment/:orderId (e.g., /v1/startorderpayment/:orderId, /v1/startticketpayment/:orderId)

refresh{ObjectName}Payment API

Business API Name: refresh{ObjectName}Payment (e.g., refreshOrderPayment, refreshTicketPayment)

REST Route: /{serviceName}-api/v1/refresh{objectName}payment/:orderId

HTTP Method: PATCH

Description: Refreshes the payment status by fetching the latest payment data from the Stripe gateway server and updating the application payment records and order status accordingly. Use this API if you prefer polling over webhooks to keep payment status synchronized.

Path Parameters:

• :orderId — The ID of the order to refresh payment for

Request Body: (Optional, typically empty)

Response:

{
  "paymentResult": {
    "success": true,
    "paymentTicketId": "payment-record-uuid",
    "orderId": "order-uuid",
    "paymentId": "pi_1234567890",
    "paymentStatus": "succeeded",
    "statusLiteral": "success"
  }
}

Auth Requirements: Login required, ownership check (user must own the order)

Kafka Event: When this API is called, a Kafka event is published to:

• Topic: {projectCodeName}-{serviceName}-service-{objectName}payment-refreshed
• Example: myproject-order-service-orderpayment-refreshed

Note:

• This API is automatically generated when StripeOrder is enabled
• Useful for applications that don't use Stripe webhooks and prefer to poll for payment status updates
• The API fetches the latest PaymentIntent status from Stripe and updates local records

callback{ObjectName}Payment API

Business API Name: callback{ObjectName}Payment (e.g., callbackOrderPayment, callbackTicketPayment)

REST Route: /{serviceName}-api/v1/callback{objectName}payment/:orderId

HTTP Method: POST

Description: Handles Stripe webhook callbacks asynchronously. This API is designed to be called by Stripe's webhook system when payment events occur. It verifies the webhook signature and processes the payment status update.

Path Parameters:

• :orderId — The ID of the order associated with the payment callback

Request Body:

{
  // Stripe webhook payload
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1234567890",
      "status": "succeeded",
      // ... other Stripe PaymentIntent data
    }
  }
}

Response:

{
  "status": "OK",
  "message": "Webhook processed successfully"
}

Auth Requirements: Public (webhook verification via Stripe signature)

Kafka Event: When this API successfully processes a webhook, a Kafka event is published to:

• Topic: {projectCodeName}-{serviceName}-service-{objectName}payment-calledback
• Example: myproject-order-service-orderpayment-calledback

Note:

• This API is automatically generated when StripeOrder is enabled
• Designed to be used as a Stripe webhook endpoint
• The webhook signature is automatically verified before processing
• Use this API if you want to use Stripe webhooks instead of polling with the refresh API

Related Documentation

• Introduction — Naming conventions and general patterns
• General Service Assets — Common assets for all services
• Payment Workflow — Complete payment integration guide and flow documentation
• Database Utility Functions — Detailed function documentation