SchoolDream+ Payment API Documentation - v2

API Overview

Welcome to the SchoolDream+ Payment API! This API enables businesses to securely process payments for their customers via MTN Momo and Airtel Money. It offers simple integration and all communication is handled through well-documented HTTP requests. We focus on secure transactions and callback mechanisms for payment status updates.

Base URL:

Authentication:

All requests must include your API credentials (API Key, Username, and Password) in the request body.

Response Format:

All responses are returned in JSON format.

Rate Limits:

We have generous rate limits in place to support high-volume transaction environments. Contact support if you require special rate-limiting considerations.

Supported Payment Methods:

• MTN Momo
• Airtel Money

Real-Time Transactions:

This API works with real-time payments, ensuring your transactions are processed immediately and status updates are sent in real-time. No sandbox environment is available at the moment.

1. Initiate Payment

Use this endpoint to initiate a payment for your customers. You will need to add parameters as they are listed below.

POST Endpoint:

Are you in Testing Environment?

Required Parameters:

Example Request:

{
  "username": "your_username",
  "password": "your_password",
  "key": "your_api_key",
  "phone": "078xxxxxxx",
  "amount": 1500,
  "requesttransactionid": "TXN98765432",
  "callbackurl": "https://yourwebsite.com/payment-status"
}

Success Response:

{
  "status": "Pending",
  "requesttransactionid": "4522233",
  "success": true,
  "responsecode": "1000",
  "transactionid": 1425,
  "message": "Transaction Pending"
}

Error Response:

{
  "status": "error",
  "message": "Missing parameter: phone"
}

2. Payment Status Callback

Once the payment provider processes the payment, we will send a final status update to your provided callback_url. This can be used to check if the transaction was successful, failed, or if there were any issues with processing the transaction.

Callback Example:

{
  "status": "Successfull",
  "requesttransactionid": "4522233",
  "transactionid": "6004994884",
  "responsecode": "01",
  "statusdesc": "Successfully Processed Transaction",
  "referenceno": "312333883"
}

Possible Payment Statuses:

• Pending - Payment is being processed
• Successfull - Payment has been successfully completed
• Failed - Payment was unsuccessful due to various reasons (e.g., insufficient funds, invalid number, etc.)

Response Codes and Descriptions:

Your server should respond with a 200 OK status to acknowledge receipt of the payment status.

Example Completion Response:

{
    "message": "success",
    "success": true,
    "request_id": "4522233"
}

3. Common Error Responses

{
  "status": "error",
  "message": "Missing parameter: amount"
}

{
  "status": "error",
  "message": "Invalid payment method selected"
}

{
  "status": "error",
  "message": "Transaction declined by payment provider"
}

{
  "status": "error",
  "message": "Unauthorized API access"
}

API Integration Examples

Here are examples of how to integrate the SchoolDream+ Payment API using different programming languages: PHP, Node.js, and Python. These examples show how to send requests to initiate payments and handle final status updates.

1. PHP Integration Example

Below is an example of how to send a payment request using PHP.

  <?php
    $url = 'https://payment.schooldream.co.rw/pay_v2';
    $data = array(
      'username' => 'your_username',
      'password' => 'your_password',
      'key' => 'your_api_key',
      'phone' => '078xxxxxxx',
      'amount' => 1500,
      'requesttransactionid' => 'TXN98765432',
      'callbackurl' => 'https://yourwebsite.com/payment-status'
    );

    // Use cURL to send the POST request
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

    $response = curl_exec($ch);
    curl_close($ch);

    echo "Response: " . $response;
  ?>
  

2. Node.js Integration Example

Below is an example of how to send a payment request using Node.js.

  const axios = require('axios');

  const paymentData = {
    username: 'your_username',
    password: 'your_password',
    key: 'your_api_key',
    phone: '078xxxxxxx',
    amount: 1500,
    requesttransactionid: 'TXN98765432',
    callbackurl: 'https://yourwebsite.com/payment-status'
  };

  axios.post('https://payment.schooldream.co.rw/pay_v2', paymentData)
    .then(response => {
      console.log('Response:', response.data);
    })
    .catch(error => {
      console.error('Error:', error);
    });
  

3. Python Integration Example

Below is an example of how to send a payment request using Python.

  import requests

  url = 'https://payment.schooldream.co.rw/pay_v2'
  data = {
    'username': 'your_username',
    'password': 'your_password',
    'key': 'your_api_key',
    'phone': '078xxxxxxx',
    'amount': 1500,
    'requesttransactionid': 'TXN98765432',
    'callbackurl': 'https://yourwebsite.com/payment-status'
  }

  response = requests.post(url, data=data)
  print('Response:', response.json())
  

Handling Payment Status Callback

After a payment request is made, you will receive a callback to your provided callback_url with the payment status. Below are examples for handling this in PHP, Node.js, and Python.

1. PHP Example - Handling Payment Status

  <?php
    // Get the incoming JSON payload
    $data = json_decode(file_get_contents('php://input'), true);

    // Check the payment status
    if ($data['status'] === 'Successfull') {
      echo "Payment successful. Transaction ID: " . $data['transactionid'];
    } else {
      echo "Payment failed. Status: " . $data['statusdesc'];
    }
  ?>
  

2. Node.js Example - Handling Payment Status

  const express = require('express');
  const app = express();
  const port = 3000;

  app.use(express.json());

  app.post('/payment-status', (req, res) => {
    const status = req.body.status;
    if (status === 'Successfull') {
      console.log('Payment successful. Transaction ID:', req.body.transactionid);
    } else {
      console.log('Payment failed. Status:', req.body.statusdesc);
    }
    res.status(200).json({ message: 'success', success: true });
  });

  app.listen(port, () => {
    console.log(`Server is running on port ${port}`);
  });
  

3. Python Example - Handling Payment Status

  from flask import Flask, request, jsonify

  app = Flask(__name__)

  @app.route('/payment-status', methods=['POST'])
  def payment_status():
      data = request.get_json()
      if data['status'] == 'Successfull':
          return f"Payment successful. Transaction ID: {data['transactionid']}", 200
      else:
          return f"Payment failed. Status: {data['statusdesc']}", 400

  if __name__ == '__main__':
      app.run(port=5000)
  

4. Deposit Funds

This endpoint allows you to deposit funds into a user's mobile money account via IntouchPay. Authentication and security checks (IP filtering, hashed credentials) are enforced. All responses are in JSON.

POST Endpoint:

POST Endpoint (TESTING ENVIRONMENT):

Authentication:

The request must include your username, password, and key which will be validated against your partner credentials.

Required Parameters:

Example Deposit Request:

{
  "username": "your_username",
  "password": "your_password",
  "key": "your_api_key",
  "transactionid": "DEP000123456",
  "referenceid": "REF000123456",
  "amount": 2500,
  "withdrawcharge": 100,
  "reason": "Group savings deposit",
  "deposit_ref_name": "Alain Serge",
  "mobilephone": "0781234567"
}

Success Response:

{
  "status": "success",
  "message": "Deposit successful",
  "transactionid": "DEP000123456",
  "responsecode": "01",
  "success": true,
  "referenceno": "INTREF202506160001"
}

Error Response Example:

{
  "status": "error",
  "message": "Missing parameter: deposit_ref_name"
}

Deposit Status Callback

Once the deposit has been processed by IntouchPay, the system will POST the final status to your callbackurl (if configured).

Callback Example:

{
  "status": "Successfull",
  "requesttransactionid": "req_66b07f35025c42.26469791",
  "transactionid": "DEP000123456",
  "responsecode": "01",
  "statusdesc": "Deposit processed successfully",
  "referenceno": "INTREF202506160001"
}

Possible Deposit Statuses:

• Pending – Deposit is being processed
• Successfull – Deposit completed successfully
• Failed – Deposit failed (e.g. invalid number, insufficient funds)

Response Codes:

Your server must respond with HTTP 200 OK to acknowledge receipt of the callback.

5. Check Balance

This endpoint allows clients to securely retrieve their account balance details. It provides the current net balance, total net credits, and total net debits, all in Rwandan Francs (RWF). Authentication and IP verification are strictly enforced. All responses are returned in JSON format.

POST Endpoint:

Authentication:

The request must include your username, password, and key. Your IP address must also be registered in the allowed IPs list.

Required Parameters:

Example Balance Request:

{
  "username": "your_username",
  "password": "your_password",
  "key": "your_api_key"
}

Success Response:

{
  "status": "success",
  "message": "Balance fetched successfully",
  "net_balance": 37500.0,
  "total_net_credits": 50000.0,
  "total_net_debits": 12500.0,
  "currency": "RWF"
}

Error Response Example:

{
  "status": "error",
  "message": "Invalid API key"
}

HTTP Status Codes:

5. Frequently Asked Questions (FAQs)

1. How do I get my API Key?

To obtain your API credentials (API Key, Username, and Password), please contact our support team via email at contact@schooldreamplus.com. Include your business name and a brief description of your intended use to speed up verification.

2. What should I do if a transaction fails?

First, review the error message returned in the response or via the callback. Common reasons for failure include:

• Invalid phone number format
• Insufficient mobile money balance
• Incorrect API credentials
• Unsupported mobile network

If the issue persists or you're unsure, please reach out to support with the requesttransactionid for further investigation.

3. How can I handle multiple payments at once?

Our API is designed to handle high-volume requests. To process multiple payments:

• Send separate API calls for each transaction in sequence or parallel (based on your system capacity).
• Ensure each request has a unique requesttransactionid to avoid duplication errors.
• Implement retry logic in case of temporary failures.

For large batches (e.g. 100+ payments), consider implementing a job queue or worker system to optimize processing.

4. How do I test payments?

Currently, there is no sandbox or testing environment. All transactions are processed in real-time. To test integration:

• Use small real transaction amounts (e.g. 100 RWF or similar).
• Ensure your callback URL is active and correctly logs the payment status response.
• Notify your team or user that the payment is for testing purposes.

Always monitor your account dashboard or payment logs for confirmation.