Sandbox Integration Flows

Overview

This document outlines the various integration flows between Membership Organizations (MO) and the Moneta network. These flows are executed after the successful deployment of necessary components.

Document Structure

Each integration flow is documented with the following components:

Business Flow
- Overview about business requirement and context of the flow
- Detailing business rules of the flow
Flow Diagram
- A visual presentation of the flow (Mermaid diagram)
Narrative
- Detailed explanation of each step in the flow
Responsibility Matrix
- Clear delineation of tasks and owners
Timeline
- Estimated duration for each step
Technical Integration Specification
- Prerequisite: What items developers need to prepare before integration
- Integration endpoint: List API, SDK operations to integrate
- Code example: Example of integration code (TypeScript/JavaScript)
- Integration Output: Expected deliverables and success criteria
Testing Procedure
- List the test cases after integration

Integration Flows

1. Setup API key

Generate and copy API key at Gateway API Setting.

2. mPass Registration Flow

2.1 Business Flow

Overview: The mPass registration flow enables Membership Organizations (MO) to onboard users into the Moneta network by registering them in bulk and distributing digital passes (mPass) for use in the ecosystem.
Business Rules:
- User data must be provided in the required format.
- Each user receives a unique mPass and QR code.
- Only registered users can activate and use the Moneta mobile application.

2.2 Flow Diagram

2.3 Narrative

MO prepares user data in the required format.
MO calls Gateway API to register users in bulk.
Gateway API processes the registration and returns the registered users.
For each registered user, MO retrieves the unique QR code.
MO distributes QR codes to respective users.
Users download the Moneta mobile application.
Users scan their assigned QR codes.
Mobile app communicates with Gateway API for device onboarding.
Gateway API validates and activates the mPass.
Mobile app stores the mPass and authenticates the user.
User receives confirmation and gains access to the app as a logged-in user.

2.4 Responsibility Matrix

Task	Owner	Support	Consulted	Informed
User Data Preparation	MO	-	Moneta	-
API Integration	MO	Moneta	-	-
QR Code Generation	Moneta	-	-	MO
QR Distribution	MO	-	-	Users
Mobile App Download	Users	-	MO	-
mPass Activation	Users	-	-	MO

2.5 Timeline

Phase	Duration	Dependencies
API Integration Setup	1 week	API Documentation Review
Batch Registration Testing	1 week	API Integration
QR Code Distribution Planning	1 week	Successful Registration
User Communication	1-2 weeks	QR Code Generation
Initial User Activation	2-4 weeks	QR Distribution

2.6 Technical Integration Specification

Prerequisite:
- Obtain API credentials and access to the Gateway API.
- Prepare user data in JSON format.
- Review API documentation for registration endpoints.
Integration Endpoints:
- POST /api/gateway/v1/mpass/users/import - Bulk import mPass users
- GET /api/gateway/v1/mpass/users/{userId}/qrcode - Get onboarding QR code for a user
- POST /api/gateway/v1/mpass/users/{userId}/devices/{requestId}/code - Onboard a user device
Code Example:

// Register users in bulk
const importUsers = async (users) => {
  const response = await fetch('/api/gateway/v1/mpass/users/import', {
    method: 'POST',
    headers: { 
      'Content-Type': 'application/json', 
      'x-api-key': 'your-api-key'
    },
    body: JSON.stringify({ 
      users: users.map(user => ({
        membershipId: user.membershipId,
        email: user.email,
        name: user.name,
        tier: user.tier
      }))
    })
  });
  return response.json();
};

// Fetch QR code for a user
const getQRCode = async (userId) => {
  const response = await fetch(`/api/gateway/v1/mpass/users/${userId}/qrcode`, {
    headers: { 'x-api-key': 'your-api-key' }
  });
  return response.json();
};

Integration Output:
- Successful API integration confirmation
- Retrieve list of registered users with IDs
- QR codes for each registered user
- Activation status reports
- User onboarding metrics
- Success Criteria:
  - 100% successful batch registration
  - Valid QR code generation for all users
  - System stability during bulk operations

2.7 Testing Procedure

Test Cases:
1. Register users with valid data (expect success and QR code generation)
2. Register users with invalid data (expect error response)
3. Attempt duplicate registration (expect proper error handling)
4. User scans QR code and activates mPass (expect activation confirmation)
5. System stability under bulk registration

3. User Debit Flow

3.1 Business Flow

Overview: The user debit flow now leverages charge batches created and managed by the MO Gateway. The MO System interacts with these batches to process user debits, track progress, and maintain a complete debit history. Charge batches are created by scheduled jobs on the MO Gateway server.
Business Rules:
- Charge batches are created automatically by MO Gateway scheduled jobs.
- MO System must poll for new charge batches to process user debits.
- Only batches with status PENDING or PROCESSED are actionable.
- Each user debit is tracked within a charge batch, and the process is complete when all user debits are processed or expired.

3.2 Flow Diagram

3.3 Narrative

MO System retrieves the list of charge batches using the Get list of charge batches API.
MO System identifies the latest charge batch with status PENDING or PROCESSED.
For each such batch, MO System fetches batch details and user debit progress using the Get a charge batch by ID API.
MO System processes the charge batch by calling the Process a charge batch API to update user debit progress.
MO System can also retrieve the history of user debits/charges using the Get list of user debits/charges API, which returns logs across multiple charge batches.
The flow is complete when all user debits in the relevant batches are processed or expired.

3.4 Responsibility Matrix

Task	Owner	Support	Consulted	Informed
Retrieve Charge Batches	MO	MO Gateway	-	-
Check Batch Status & Progress	MO	MO Gateway	-	-
Process Charge Batch	MO	MO Gateway	-	-
Retrieve Debit/Charge History	MO	MO Gateway	-	-
Monitor Completion	MO	MO Gateway	-	-

3.5 Timeline

Phase	Duration	Dependencies
API Integration Setup	1 week	API Documentation Review
Charge Batch Processing Testing	1-2 weeks	API Integration
Production Deployment	1 week	Successful Testing
Initial Monitoring	2 weeks	Production Deployment

3.6 Technical Integration Specification

Prerequisite:
- Obtain API credentials and access to the MO Gateway.
- Review API documentation for charge batch and debit endpoints.
- Ensure TLS 1.2+ and IP whitelisting are in place; requests must be signed.
Integration Endpoints:
Code Example:

// Get list of charge batches
const chargeBatches = await fetch('/api/gateway/v1/user-billing/charge-batches', {
  headers: { 'x-api-key': '<your-api-key>' }
}).then(res => res.json());

// Get charge batch by ID
const batchId = chargeBatches.data.find(batch => batch.status === 'PENDING' || batch.status === 'PROCESSED')?.id;
const batchDetails = await fetch(`/api/gateway/v1/user-billing/charge-batches/${batchId}`, {
  headers: { 'x-api-key': '<your-api-key>' }
}).then(res => res.json());

// Process a charge batch
await fetch(`/api/gateway/v1/user-billing/charge-batches/${batchDetails.data.batchCode}/process`, {
  method: 'POST',
  headers: { 'x-api-key': '<your-api-key>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ /* user debit results */ })
});

// Get list of user debits/charges
const debits = await fetch('/api/gateway/v1/user-billing/debits', {
  headers: { 'x-api-key': '<your-api-key>' }
}).then(res => res.json());

Integration Output:
- Successful API integration for all endpoints
- Charge batch and user debit processing reports
- Success/failure metrics
- Transaction logs
- Success Criteria:
  - 100% successful charge batch retrieval and processing
  - Accurate tracking of user debit progress
  - System stability during batch operations
  - Complete and accurate debit/charge history
Security Requirements:
- TLS 1.2 or higher required
- IP whitelisting
- Request signing
Testing Procedure:
- Test Cases:
  1. Retrieve charge batches (expect correct data and pagination)
  2. Fetch and process charge batch (expect success and accurate status)
  3. Retrieve user debit/charge history (expect logs across batches)
  4. System stability under batch processing
  5. Flow termination when all user debits are processed or expired

4. Settlement Flow

4.1 Business Flow

Overview: The settlement flow now leverages billing cycles created and managed by the MO Gateway. The MO System interacts with these billing cycles to process user payments, track progress, and maintain a complete payment history. Billing cycles are created by scheduled jobs on the MO Gateway server.
Business Rules:
- Billing cycles are created automatically by MO Gateway scheduled jobs.
- MO System must poll for new billing cycles to process user payments.
- Only billing cycles with status INIT or IN_PROGRESS are actionable.
- User payment progress is tracked in a downloadable statement file, and only the status column is updated by MO System.
- The flow is complete when the billing cycle processing time is overdue; unpaid users are marked as UNPAID.

4.2 Flow Diagram

4.3 Narrative

MO System retrieves the list of billing cycles using the Get all billing cycles API.
MO System identifies the latest billing cycle with status INIT or IN_PROGRESS.
For each such billing cycle, MO System fetches billing cycle details and status using the Get a billing cycle by code API.
MO System downloads the user statements CSV file using the Get MO Statement Records API, which tracks user payment progress.
MO System updates the user payment progress in the file (status column only).
MO System uploads the updated file using the Update MO Statement Status API. This can be done multiple times before the billing cycle expires.
After the billing cycle expires, any user payments not updated are marked as UNPAID.
The flow is complete when the billing cycle processing time is overdue.

4.4 Responsibility Matrix

Task	Owner	Support	Consulted	Informed
Retrieve Billing Cycles	MO	MO Gateway	-	-
Check Billing Cycle Status	MO	MO Gateway	-	-
Download User Statements	MO	MO Gateway	-	-
Update User Payment Progress	MO	MO Gateway	-	-
Upload Updated Statement	MO	MO Gateway	-	-
Monitor Completion	MO	MO Gateway	-	-

4.5 Timeline

Phase	Duration	Dependencies
API Integration Setup	1 week	API Documentation Review
Billing Cycle Processing Testing	1-2 weeks	API Integration
Production Deployment	1 week	Successful Testing
Initial Monitoring	2 weeks	Production Deployment

4.6 Technical Integration Specification

Prerequisite:
- Obtain API credentials and access to the MO Gateway.
- Review API documentation for billing cycle and statement endpoints.
- Ensure TLS 1.2+ and IP whitelisting are in place; requests must be signed.
Integration Endpoints:
Code Example:

// Get list of billing cycles
const billingCycles = await fetch('/api/gateway/v1/settlement/billing-cycles', {
  headers: { 'x-api-key': '<your-api-key>' }
}).then(res => res.json());

// Get billing cycle by code
const cycleCode = billingCycles.data.find(cycle => cycle.status === 'INIT' || cycle.status === 'IN_PROGRESS')?.code;
const cycleDetails = await fetch(`/api/gateway/v1/settlement/billing-cycles/${cycleCode}`, {
  headers: { 'x-api-key': '<your-api-key>' }
}).then(res => res.json());

// Download MO statement records (CSV)
const statementFile = await fetch(`/api/gateway/v1/settlement/billing-cycles/files/${cycleCode}/mo-statements`, {
  headers: { 'x-api-key': '<your-api-key>' }
});
// ... process and update the status column in the CSV file ...

// Upload updated statement file
const formData = new FormData();
formData.append('file', updatedCsvFile);
await fetch(`/api/gateway/v1/settlement/billing-cycles/files/${cycleCode}/mo-statements`, {
  method: 'POST',
  headers: { 'x-api-key': '<your-api-key>' },
  body: formData
});

Integration Output:
- Successful API integration for all endpoints
- Billing cycle and user payment processing reports
- Success/failure metrics
- Transaction logs
- Success Criteria:
  - 100% successful billing cycle retrieval and processing
  - Accurate tracking of user payment progress
  - System stability during batch operations
  - Complete and accurate payment history
Security Requirements:
- TLS 1.2 or higher required
- IP whitelisting
- Request signing
Testing Procedure:
- Test Cases:
  1. Retrieve billing cycles (expect correct data and pagination)
  2. Fetch and process billing cycle (expect success and accurate status)
  3. Download and update user statements (expect correct CSV format and status updates)
  4. Upload updated statement file (expect success and accurate status)
  5. System stability under batch processing
  6. Flow termination when billing cycle processing time is overdue

References

API Documentation
Deployment Guide
Technical Support Contacts
Troubleshooting Guide

Overview​

Document Structure​

Integration Flows​

1. Setup API key​

2. mPass Registration Flow​

2.1 Business Flow​

2.2 Flow Diagram​

2.3 Narrative​

2.4 Responsibility Matrix​

2.5 Timeline​

2.6 Technical Integration Specification​

2.7 Testing Procedure​

3. User Debit Flow​

3.1 Business Flow​

3.2 Flow Diagram​

3.3 Narrative​

3.4 Responsibility Matrix​

3.5 Timeline​

3.6 Technical Integration Specification​

4. Settlement Flow​

4.1 Business Flow​

4.2 Flow Diagram​

4.3 Narrative​

4.4 Responsibility Matrix​

4.5 Timeline​

4.6 Technical Integration Specification​

References​