Authentication

All API requests require JWT (JSON Web Token) authentication. Tokens expire after 1 hour. Use refresh tokens (7-day expiry) to obtain new access tokens without re-authenticating. Always include the token in the Authorization header of every request.

Admin Sign-Up

Use Case: Register your primary admin account when first setting up NORAH. This creates the main account that can manage all other users and merchants in your organization.

⚠️ Important: After signup, you must confirm your email address before you can sign in. Check your inbox for a confirmation link or code.

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@company.com",
  "password": "SecurePass123!",
  "companyName": "Tech Solutions Ltd",
  "address": "123 Business St, Harare",
  "description": "E-commerce platform",
  "phone": "263771234567",
  "publicEmail": "info@company.com",
  "returnUrl": "https://company.com/return",
  "webServiceUrl": "https://api.company.com/webhook",
  "website": "www.company.com"
}

Response (201 Created):

{
  "timestamp": "2025-04-05 11:02:12",
  "statusCode": 201,
  "status": "CREATED",
  "message": "Successfully created new resource",
  "data": {
    "id": 1,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@company.com",
    "role": "ADMIN",
    "enabled": false,
    "companyName": "Tech Solutions Ltd"
  }
}

Sign In

Use Case: Authenticate with your email and password to receive JWT access and refresh tokens. This is the first step in your integration flow.

Best Practice: Implement automatic token refresh 5-10 minutes before expiry to prevent service interruption.

Response Includes: Access token (1 hour), Refresh token (7 days), user role, and other user details for personalization.

Request Body:

{
  "email": "john.doe@company.com",
  "password": "SecurePass123!"
}

Response (200 OK):

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJh...",
  "tokenExpiryDate": "Sat, 05 Apr 2025 15:11:21 GMT",
  "user_id": 1,
  "role": "ADMIN",
  "fullName": "John Doe",
  "email": "john.doe@company.com"
}

Using the Token

Include the JWT token in the Authorization header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

User Management

Manage your team members and company administrators. Users can be assigned different roles (SUPER, ADMIN, MERCHANT) with corresponding permission levels. Each user has their own login credentials and security credentials.

Create Super User

Use Case: Create a system administrator with elevated privileges. Only existing SUPER users can perform this action.

When to Use: During initial system setup when you need to grant another person system-wide administrative access.

Request Body:

{
  "firstName": "Super",
  "lastName": "Admin",
  "email": "super@norah.com",
  "password": "SuperPass123!"
}

Create Secondary Admin

Use Case: Add team members with admin privileges to manage merchants and view company transactions.

When to Use: When onboarding team members who need administrative access but not system-wide privileges.

Request Body:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@company.com",
  "password": "SecurePass456!",
  "phone": "263771234568"
}

Get All Users

Use Case: Retrieve a list of all users (admins and regular users) in your company to manage team members.

When to Use: In a user management dashboard or admin panel to display team members, filter by role, or manage permissions.

Update User

Update user details including role and status.

Request Body:

{
  "fullName": "Jane Smith",
  "email": "jane.smith@company.com",
  "role": "ADMIN",
  "status": true,
  "notes": "Secondary admin for operations"
}

Delete User

Delete a user account. You cannot delete your own account.

Get User Secret

Retrieve user's transaction signing secret for JWT token generation.

Merchant Management

Merchants are the businesses that process payments through NORAH. Every merchant goes through a lifecycle: creation → setup → activation → transaction processing. Each merchant can have their own charges, settlement accounts, and payment methods configured.

Create Merchant Account

Use Case: Register a new business that will process payments through your platform. Merchants are created in DEVELOPMENT status pending review.

Next Steps: After creation, configure merchant-specific charges, set return URLs for payment redirects, and activate when ready for transactions.

Request Body:

{
  "merchantName": "ABC Store",
  "merchantAddress": "456 Commerce Ave, Harare",
  "merchantPhone": "263771234570",
  "merchantEmail": "store@abcstore.com",
  "merchantCountry": "Zimbabwe",
  "merchantCity": "Harare",
  "merchantWebsite": "www.abcstore.com",
  "merchantDescription": "Online retail store",
  "returnUrl": "https://abcstore.com/payment/return",
  "webServiceUrl": "https://api.abcstore.com/webhook"
}

Response (201 Created):

{
  "timestamp": "2025-04-05 11:02:12",
  "statusCode": 201,
  "status": "CREATED",
  "message": "Merchant account created successfully.",
  "data": {
    "merchantId": 1,
    "merchantName": "ABC Store",
    "merchantEmail": "store@abcstore.com",
    "merchantUid": "uuid-string-here"
  }
}

List Merchants

Use Case: Display all merchants in your dashboard or management interface to view their status, contact info, and payment history.

When to Use: In admin dashboards, reporting tools, or when filtering merchants by status or location.

Activate Merchant

Use Case: Approve a merchant account for live transaction processing after completing verification and setup.

When to Use: Once merchant details are verified and they're ready to start accepting payments.

Inactivate Merchant

Use Case: Temporarily or permanently suspend a merchant from processing transactions due to compliance issues, non-payment, or merchant request.

Impact: Merchant can no longer initiate transactions. Existing transactions continue processing and settling.

Get Merchant Secret

Use Case: Retrieve the merchant's secret key used to digitally sign transaction tokens and verify webhook callbacks.

Security: Keep this secret secure. Treat it like a password and never expose it in client-side code or public repositories.

Charges & Fees

Configure transaction fees and charges. The system automatically calculates and applies charges based on thresholds and transaction details. Charges can be fixed (FLAT) or percentage-based. System charges apply globally; merchant charges apply to specific merchants.

Add Merchant Charge

Use Case: Configure merchant-specific fees. For example, charge ABC Store 2.5% but charge XYZ Corp 2.0% due to volume agreement.

When to Use: To implement tiered pricing, promotional rates, or per-merchant fee structures. Merchant charges override system charges.

Request Body:

{
  "merchantUserName": "merchant_email@norah.com",
  "chargeType": "PERCENTAGE",
  "chargeSource": "MERCHANT",
  "chargeCategory": "TRANSACTION",
  "status": "ACTIVE",
  "currency": "USD",
  "value": 1.5,
  "statementNarration": "Merchant transaction fee",
  "minThreshold": 0,
  "maxThreshold": 1000000000,
  "plAccount": "MERCHANT_CHARGE_001"
}

Get Merchant Charges

Use Case: View all configured merchant-specific charges to verify pricing structures and verify charges are applied correctly.

When to Use: In admin dashboards when auditing pricing or troubleshooting charge calculations.

Get Charges by Merchant

Use Case: Retrieve charges applicable to a specific merchant to show them their fee structure.

When to Use: When a merchant needs to understand their charges or for displaying fees in merchant portal.

Update Merchant Charge

Use Case: Modify merchant fees due to renegotiated terms, volume changes, or promotional campaigns.

When to Use: When adjusting merchant pricing or applying temporary promotions.

Delete Merchant Charge

Use Case: Remove a merchant's custom charge configuration when restructuring fees or ending promotional pricing.

After Deletion: Merchant will revert to system-level charges for their transactions.

Transactions

Manage the complete payment lifecycle. Generate transaction tokens before payment initiation, confirm transactions after customer completes payment, and track transaction status in real-time. Each transaction receives a unique trace ID for tracking and settlement.

Generate User Transaction Token

Use Case: Create a secure token that encodes payment details. Share this token with your end-user's client-side payment application to initiate payment.

Important: Token expires in 60 seconds for security. Generate a fresh token for each payment attempt. Response includes checkout URL to redirect customer to NORAH payment page.

Request Body:

{
  "amount": 100.00,
  "currency": "USD"
}

Response (200 OK):

{
  "timestamp": "2025-04-05T11:02:12",
  "statusCode": 200,
  "status": "OK",
  "message": "Successfully created a user payment token",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "url": "https://api.company.com/check-out?token=...&type=u"
  }
}

Generate Merchant Transaction Token

Use Case: Similar to user transaction token but for merchant-initiated payments. Merchants use this when they need to charge customers directly.

When to Use: When merchant initiates payment (e.g., subscription billing, invoice payment) rather than customer self-service payment.

Request Body:

{
  "amount": 500.00,
  "currency": "USD"
}

Confirm Transaction

Use Case: Complete the payment initiation with customer's chosen payment method. This triggers the payment processing and generates a trace ID for tracking.

Payment Methods Supported: ZIMSWITCH, OMARI, INNBUCKS, ECOCASH, VISA_MASTER. Save the trace ID to track transaction status and handle callbacks.

Request Body:

{
  "user": "john.doe@company.com",
  "amount": 100.00,
  "charge": 2.50,
  "currency": "USD",
  "paymentMethod": "ZIMSWITCH",
  "phoneNumber": "263771234567",
  "merchantUid": "merchant_uid_here"
}

Check Transaction Status

Use Case: Poll transaction status when you don't receive a webhook callback. Essential for reconciliation and error handling.

Status Values: PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED. Check status before finalizing order in your system.

Request Body:

{
  "trace": "transaction_trace_uuid"
}

Response (200 OK):

{
  "status": 200,
  "message": "Transaction status retrieved successfully",
  "data": {
    "trace": "transaction_trace_uuid",
    "status": "COMPLETED",
    "amount": 100.00,
    "currency": "USD",
    "paymentMethod": "ZIMSWITCH",
    "timestamp": "2025-04-05T11:02:12"
  }
}

Cancel Transaction

Use Case: Cancel a transaction that hasn't been fully processed yet. Useful for handling customer cancellations or order changes.

Important: Only PENDING and PROCESSING transactions can be cancelled. Already COMPLETED transactions require refund instead.

Request Body:

{
  "trace": "transaction_trace_uuid"
}

Response (200 OK):

{
  "status": 200,
  "message": "Transaction cancelled successfully",
  "data": {
    "trace": "transaction_trace_uuid",
    "status": "CANCELLED",
    "refundedAmount": 100.00
  }
}

Get User Transactions

Use Case: Display transaction history for the authenticated user in their personal account or transaction dashboard.

When to Use: In user account pages showing payment history, receipts, or transaction details.

Response (200 OK):

{
  "status": 200,
  "message": "Transactions retrieved successfully",
  "data": [
    {
      "trace": "trace_123",
      "amount": 100.00,
      "currency": "USD",
      "status": "COMPLETED",
      "paymentMethod": "ZIMSWITCH",
      "timestamp": "2025-04-05T10:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 25
  }
}

Get Merchant Transactions

Use Case: View all transactions processed by a merchant for settlement, reporting, and reconciliation.

Permission: Admins see all merchants; merchants only see their own transactions. Essential for merchant dashboards.

Response (200 OK):

{
  "status": 200,
  "message": "Merchant transactions retrieved successfully",
  "data": [
    {
      "trace": "trace_456",
      "merchantId": "merchant_123",
      "amount": 500.00,
      "currency": "USD",
      "status": "COMPLETED",
      "charges": 12.50,
      "netAmount": 487.50,
      "timestamp": "2025-04-05T10:15:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150
  }
}

Get Merchant Charges

Use Case: Retrieve all charge transactions applied to a specific merchant. Useful for reconciliation and understanding fee deductions.

When to Use: For charge auditing and merchant billing statements.

Get All Transactions

Use Case: Generate comprehensive reports across all merchants. Use filters to analyze specific payment methods, time periods, or transaction amounts.

Filters Available: Search (trace/merchant name), Status, Currency, Date range. Essential for executive dashboards and financial reporting.

Query Parameters:

page=1              (pagination start)
per_page=10         (results per page)
search=             (optional: trace or merchant name)
status=             (optional: PENDING, COMPLETED, FAILED)
currency=USD        (optional: filter by currency)
start_date=         (optional: YYYY-MM-DD)
end_date=           (optional: YYYY-MM-DD)

Get Transaction Details

Use Case: Get comprehensive details of a specific transaction including all charges applied, payment method used, and settlement details.

When to Use: When investigating transaction issues, generating detailed receipts, or auditing payment processing.

Response (200 OK):

{
  "status": 200,
  "message": "Transaction details retrieved successfully",
  "data": {
    "transactionId": "trans_789",
    "trace": "trace_789",
    "merchant": "ABC Store",
    "amount": 1000.00,
    "currency": "USD",
    "charges": 25.00,
    "netAmount": 975.00,
    "paymentMethod": "ZIMSWITCH",
    "status": "COMPLETED",
    "timestamp": "2025-04-05T10:00:00",
    "chargesBreakdown": [
      {
        "type": "PERCENTAGE",
        "value": 2.5,
        "amount": 25.00
      }
    ]
  }
}

Generate Receipt

Use Case: Generate a formatted PDF receipt for customer or merchant to download. Include transaction details, charges breakdown, and payment method.

When to Use: After successful transaction completion or when customer requests receipt.

Request Body:

{
  "transactionId": "transaction_id_123"
}

Response (200 OK):

{
  "status": 200,
  "message": "Receipt generated successfully",
  "data": {
    "receiptId": "receipt_789",
    "receiptUrl": "https://api.norah.co.zw/receipts/receipt_789.pdf",
    "downloadUrl": "https://api.norah.co.zw/receipts/download/receipt_789",
    "transactionId": "trans_123",
    "amount": 500.00,
    "currency": "USD",
    "charges": 12.50,
    "timestamp": "2025-04-05T10:30:00"
  }
}

Get Recent Transactions

Use Case: Display the most recent transactions in your dashboard. Useful for monitoring activity and detecting issues.

When to Use: On dashboard to show live transaction feed to admins and merchants.

Query Parameters:

search=   (optional: merchant name or trace)
per_page=10  (default)
page=1       (pagination)

Response (200 OK):

{
  "status": 200,
  "message": "Recent transactions retrieved",
  "data": [
    {
      "transactionId": "trans_100",
      "trace": "trace_100",
      "merchant": "ABC Store",
      "amount": 250.00,
      "currency": "USD",
      "status": "COMPLETED",
      "paymentMethod": "ZIMSWITCH",
      "timestamp": "2025-04-05T15:45:00"
    },
    {
      "transactionId": "trans_99",
      "trace": "trace_99",
      "merchant": "XYZ Shop",
      "amount": 100.00,
      "currency": "USD",
      "status": "COMPLETED",
      "paymentMethod": "ECOCASH",
      "timestamp": "2025-04-05T15:40:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 2
  }
}

Testing & Payment Methods

NORAH integrates with multiple payment methods to give merchants flexibility. Each payment method has specific requirements, flow, and testing endpoints. For development, use the Development URL to test with sandbox accounts before going live.

Payment Methods Overview

NORAH supports multiple payment methods to cater to different customer preferences:

Test Charge Calculation

Use Case: Verify charge calculations before initiating transactions. Shows how much will be charged as fees on a given amount.

When to Use: During development to validate pricing logic or in customer-facing apps to show transparent fee breakdown.

Request Body:

{
  "amount": 1000,
  "currency": "USD",
  "user_email": "admin@company.com"
}

Response (200 OK):

{
  "status": 200,
  "message": "Charge calculation completed",
  "data": {
    "amount": 1000.00,
    "currency": "USD",
    "charges": 25.00,
    "chargesBreakdown": [
      {
        "type": "PERCENTAGE",
        "value": 2.5,
        "amount": 25.00
      }
    ],
    "netAmount": 975.00
  }
}