Skip to main content

NeoPaaS: Getting Started

This section outlines the complete onboarding process for new merchants and clients joining the NeoPaaS platform. It is intended for merchant and ECR company’s technical and integration teams, ensuring a smooth connection between the ECR software and NeoPaaS infrastructure. It ensures merchant accounts are configured correctly, terminals are linked appropriately, and payment workflows are enabled in line with system architecture and compliance requirements. The guide covers the process from initial registration, technical configuration, and integration testing, to operational readiness.

1. Merchant Account Registration​

1.1 Initiation​

Merchants may be onboarded through one of the following channels:

  • Direct onboarding via NeoPaaS Merchant Portal.
  • Facilitated onboarding through NeoPaaS internal team.

1.2 General Required Information​

  • Business Name – Legal or trading name

  • Merchant Representative – Name of authorized user

  • Email Address – Used as login credential

  • Phone Number – For communication

  • City & Region – KSA-specific configurations

1.3 Branch Creation​

Each physical or operational location must be registered as a branch. Required Fields:

  • Branch Name (e.g., Branch 01 – Riyadh)
  • Region, City, and District

1.4 Cashier Setup​

Each cashier account is tied to a specific branch. Required Fields:

  • Cashier Name
  • Username (used for login)
  • Password

1.5 Terminal Registration​

Each POS terminal is tied to a cashier and must be uniquely registered. Required Fields:

  • Terminal ID (from MSP)
  • Terminal Brand and Model
  • Associated Cashier and Branch

2. MSP Assignment & Management​

2.1 MSP Selection​

The MSP name, terminal model, and MADA package must match the hardware issued to the merchant.

2.2 Unregistered MSPs​

If the merchant’s MSP is not listed

  • Submit a request via PM
  • NeoPaaS team initiates MSP onboarding via Super Admin Portal.

3. NeoPaaS Client Application Activation​

3.1 Test Environment Setup​

a. Testing on a Physical POS Terminal

If the device being used for testing is a test POS terminal, only installing the NeoPaaS Client App is sufficient. Once installed, ensure the terminal is registered and activated under the correct merchant and cashier account in the NeoPaaS Merchant Portal. The client app will automatically detect the terminal configuration and be ready for transaction testing.

b. Testing in a Simulated Environment

If the testing device is a mobile device or non-POS terminal, the Mada Simulator App must be installed to emulate POS terminal behavior.

Follow the steps below:

  1. Locate and download the Mada Simulator APK from the shared WorkDrive folder.

  2. Install and launch the simulator on your test device.

  3. When prompted, enter and save the Terminal ID that was created during onboarding and will be used for testing.

  4. After saving the Terminal ID, install the NeoPaaS Client App on the same device.

  5. You may now proceed to initiate test transactions using the NeoPaaS Client App, which will communicate with the Mada Simulator to simulate real transaction flows.

Note: Always install and configure the Mada Simulator before installing the Client App to ensure proper App2App communication.

3.2 Launch​

Once the terminal information is set up during onboarding, no additional login or manual configuration is required. On launch, the client app will display the terminal ID and the associated cashier name, ready for immediate use.

Note: Ensure that the cashier account is linked to the correct terminal. To verify, log in to the Merchant Portal, navigate to the Terminals page, and check that the terminal ID and cashier name are correctly paired in the table. If they are not, go to the Details section of the desired terminal and reassign the cashier from the list of available onboarded cashiers.

4. ECR Integration (Merchant System Integration)​

The merchant's cashier system (ECR) must be able to send purchase, refund, and reconciliation requests to NeoPaaS via the integration layer (API communication).

4.1 Integration Methods​

Use the provided NeoPaaS Postman Collection to connect your ECR system to the NeoPaaS APIs.

Note: For API authentication, use the cashier account credentials (username and password) created during the onboarding process. These credentials will serve as the API login details.

4.2 Testing Transactions​

Responsible: Merchant / ECR Technical Team

  • Perform a test purchase from the ECR → Client App.
  • Confirm the transaction is received in the Client App and appears in the Merchant Portal.
  • Perform a test refund and confirm it is received in the Client App and appears in the Merchant Portal.
  • Trigger a reconciliation and check the reconciliation report in the portal.
  • Test declined transaction handling.

5. Operational Readiness Verification​

Before go-live, the following checks must be completed

  • Terminals activated and authenticated – Merchant IT / Support
  • Sample transaction processed – Support Team
  • Reconciliation, Refund triggered successfully – QA
  • Reports and metrics visible on portal – Merchant + QA

6. Support & Escalation​

7. Documentation Access​

All technical documentation and API references are available via the NeoPaaS Developer Portal