Estate Middleware Payment API

Comprehensive RESTful API for estate management and payment processing with secure authentication and real-time webhooks.

API Overview

The Estate Middleware Payment API provides a comprehensive solution for managing estate operations, payment processing, and account management. Built with security and scalability in mind, this API enables seamless integration with your estate management systems.

Key Features
  • Complete estate lifecycle management
  • Secure payment processing with virtual accounts
  • Real-time webhook notifications
  • Comprehensive error handling and validation
  • RESTful design with JSON responses

Base URL

All API requests should be made to the following base URL:

https://estate.urbex.africa/payments/

Note: All endpoints are relative to this base URL. For example, to access the estate creation endpoint, use: https://estate.urbex.africa/payments/api/add_new_estate.php

Authentication

All API endpoints require authentication using a valid API key. Include your API key in the request headers for every API call.

Required Header

X-API-KEY: your-active-enc_key
Important Security Notes
  • Keep your API key secure and never expose it in client-side code
  • Requests without a valid API key will be rejected with 400 Bad Request
  • Inactive or invalid keys will result in authentication failure
  • Contact support to obtain or regenerate your API key

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

200
OK - Request successful
201
Created - Resource created
400
Bad Request - Invalid input
401
Unauthorized - Invalid API key
404
Not Found - Resource not found
500
Server Error - Internal error

Error Response Format

When an error occurs, the API returns a standardized error response with helpful information for debugging:

Error Structure

{
  "status": false,
  "error": {
    "code": 7003,
    "message": "Invalid estate code provided",
    "hints": [
      "Ensure the estate code exists in the system",
      "Check for typos in the estate code parameter",
      "Contact support if the issue persists"
    ]
  }
}

Error Fields

Field Type Description
status boolean Always false for error responses
error.code integer Unique error code for programmatic handling
error.message string Human-readable error description
error.hints array Helpful suggestions for resolving the error

API Endpoints

Complete reference for all available API endpoints with detailed parameters, examples, and responses.

1. Add New Estate

Creates a new estate in the system with the provided details. This endpoint initializes the estate with basic information and generates a unique estate ID.

POST /api/add_new_estate.php

Headers

Content-Type: application/x-www-form-urlencoded
X-API-KEY: your-active-enc_key

Body Parameters

Parameter Type Required Description
estate_name string required Full name of the estate
estate_code number required Unique identifier code for the estate
contact_email string optional Primary contact email address
contact_phone string optional Primary contact phone number

Success Response (201 Created)

{
  "status": true,
  "message": "Estate created successfully.",
  "data": {
    "estate_id": 45,
    "merchant_id": "MERCHANT_UNIQUE_ID",
    "estate_name": "Ikota Gardens",
    "estate_code": "050554",
    "contact_email": "contact@ikota.com",
    "contact_phone": "08012345***"
  }
}

2. Get Estate Information

Retrieves comprehensive information about an estate including wallet details, metadata, and statistics.

GET /api/get_estate_info.php

Headers

X-API-KEY: your-active-enc_key

Query Parameters

Parameter Type Required Description
estate_code string required Unique estate identifier code

Success Response (200 OK)

{
    "status": true,
    "text": "Estate information retrieved successfully.",
    "data": {
        "estate_id": 1,
        "estate_name": "AGBAMI ESTATE",
        "estate_code": "504029",
        "contact_email": "okekejohnpaul12@gmail.com",
        "contact_phone": "09032210788",
        "created_at": "2025-06-24 12:19:04",
        "wallet_balance": 7000,
        "currency": "NGN"
    },
    "time": "27-06-25 02:09:55AM",
    "method": "GET",
    "endpoint": "/api/estate/get_estate_info.php",
    "error": []
}

3. Create Estate Account

Creates a new virtual account for an estate with the specified account holder details and business information.

POST /api/create_estate_account.php

Headers

Content-Type: application/x-www-form-urlencoded
X-API-KEY: your-active-enc_key

Body Parameters

Parameter Type Required Description
estate_id integer required ID of the estate to create account for
first_name string required Account holder's first name
last_name string required Account holder's last name
other_name string required Account holder's middle name
bvn string required Bank Verification Number
dob YYYY-MM-DD required Date of birth in ISO format
phone_number string required Account holder's phone number

Success Response (200 OK)

{
  "status": true,
  "message": "Estate account created successfully.",
  "data": {
    "estate_id": 12,
    "tag": "sarepay_estate_12_1625074800",
    "internal_reference": "intref_60e2b5d25fa6f8.12345678",
    "gateway_reference": "684c221422907396231749819924",
    "account_name": "Jane Doe",
    "account_number": "1234567890",
    "bank_name": "SarePay Bank",
    "created_at": "2025-06-25T14:30:00+01:00"
  }
}

4. Get Reserved Accounts

Retrieves all virtual accounts associated with a specific estate, including account details and creation timestamps.

GET /api/get_reserved_accounts.php

Headers

X-API-KEY: your-active-enc_key

Query Parameters

Parameter Type Required Description
estate_code string required Estate code to fetch accounts for

Success Response (200 OK)

{
  "status": true,
  "message": "Reserved accounts for estate IKOTA1 fetched successfully.",
  "data": {
    "estate_code": "IKOTA1",
    "count": 2,
    "accounts": [
      {
        "id": 45,
        "tag": "sarepay_estate_12_1625074800",
        "internal_reference": "intref_60e2b5d25fa6f8.12345678",
        "gateway_reference": "684c221422907396231749819924",
        "account_name": "Jane Doe",
        "account_number": "1234567890",
        "bank_name": "SarePay Bank",
        "created_at": "2025-06-25T14:30:00+01:00"
      }
    ]
  }
}

5. Credit Estate

Credits an estate's wallet with the specified amount, including optional charges and transaction references for tracking.

POST /api/credit_estate.php

Headers

Content-Type: application/x-www-form-urlencoded
X-API-KEY: your-active-enc_key

Body Parameters

Parameter Type Required Description
estate_id integer required ID of the estate to credit
amount decimal required Amount to credit (must be > 0)
reference string required Internal transaction reference

Success Response (200 OK)

{
  "status": true,
  "message": "Estate 12 credited successfully.",
  "data": {
    "estate_id": 12,
    "amount": 1000.00,
    "charge": 10.00,
    "balance_before": 5000.00,
    "balance_after": 5990.00,
    "internal_reference": "intref_60e2b5d25fa6f8.12345678"
    "timestamp": "2025-06-25T12:34:56+01:00"
  }
}

6. Webhook: Collection Notification

Receives payment notifications from the gateway and processes them to update estate balances and notify merchants.

POST /api/webhook_collection.php

Headers

Content-Type: application/json
X-API-KEY: your-active-enc_key

Incoming Payload

Your service receives this payload from the payment gateway:

{
  "event": "collection.virtualaccount.successful",
  "data": {
    "id": 302161,
    "domain": "live",
    "status": "success",
    "reference": "wls_Y3RZE1N2VGTMLB71749824349",
    "amount": 100000,
    "message": null,
    "gateway_response": "Successful",
    "paid_at": "2025-06-25T12:34:56.000Z",
    "created_at": "2025-06-25T12:34:56.000Z",
    "channel": "dedicated_nuban",
    "currency": "NGN",
    "customer": {
      "id": 89929267,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "customer_code": "CUS_abc123def456",
      "phone": "+2348012345678",
      "metadata": null,
      "risk_action": "default"
    }
  },
  "hash": "5W8bD41Xc4WQkfEgfVzM9DjdUME8nN5lt/tMGjf62kA="
}

Internal Processing

When a webhook is received, the system performs the following actions:

  1. Log Payload: Store the raw webhook payload for audit purposes
  2. Validate Signature: Verify the webhook authenticity using the hash
  3. Parse Data: Extract transaction details and find associated reserved accounts
  4. Update Records: Insert detailed transaction record and update estate balance
  5. Notify Merchant: Send notification to the merchant's configured webhook URL

Merchant Notification Payload

The system sends this payload to your configured webhook URL:

{
  "event": "estate.credit",
  "timestamp": "2025-06-25T12:34:56+01:00",
  "estate": {
    "id": 12,
    "code": "IKOTA1",
    "name": "Ikota Gardens"
  },
  "customer_reference": "wls_Y3RZE1N2VGTMLB71749824349",
  "transaction": {
    "amount": 1000.00,
    "currency": "NGN",
    "reference": "intref_60e2b5d25fa6f8.12345678",
    "status": "successful",
    "channel": "dedicated_nuban"
  },
  "sender": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+2348012345678"
  },
  "recipient": {
    "account_number": "1234567890",
    "account_name": "Ikota Gardens Ltd",
    "bank_name": "SarePay Bank"
  },
  "meta": {
    "balance_before": 5000.00,
    "balance_after": 6000.00,
    "processed_at": "2025-06-25T12:34:56+01:00"
  }
}

Expected Response

Your webhook endpoint should respond with:

{
  "status": "success",
  "message": "Collection processed successfully."
}