API Documentation - Mago Flash

Complete guide to integrating with Mago Flash API.

Getting Started

Mago Flash provides a simple and secure way to accept mobile money payments in your applications. This documentation will guide you through the integration process step by step.

Here's how the platform works:

1. You request an available phone number for your visitors to make a payment.
2. The API provides you with a phone number.
3. You provide this number to your customer for them to make a transfer.
4. After your customer completes the payment, they receive a confirmation code.
5. The customer uses this code to confirm their payment on your website.
6. Once confirmed, the paid amount is transferred to your account.

So, without further ado, let's see how to do all this!

Integration Steps

Step 1: Account Setup

To get started with Mago Flash:

1. Create a merchant account at https://magoflash.com/merchant/.
2. Complete the verification process.
3. Access your merchant dashboard.

Step 2: API Token Generation

Generate your API tokens:

1. Navigate to the Tokens section in your dashboard.
2. Click "Generate New Token".
3. Copy and use your token to make requests from your site.

Step 3: Basic Integration

Follow these steps to implement the basic payment flow:

1. Request a payment number for your customer.
2. The customer sends payment to the provided number.
3. Verify the transaction using the confirmation code or the transaction ID.
4. Handle the transaction response.

Example Implementation

// Using JavaScript with fetch
const apiToken = 'YOUR_API_TOKEN';

// Request a payment number
async function requestPaymentNumber(operatorName = null) {
  const url = new URL('https://magoflash.com/api/payment-phone');
  if (operatorName) url.searchParams.append('operatorName', operatorName);
  
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Verify transaction
async function verifyTransaction(code, transactionId, phoneNumber) {
  const response = await fetch('https://magoflash.com/api/verify-transaction', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      code,
      transactionId,
      phoneNumber
    })
  });
  
  return await response.json();
}

// Example usage
requestPaymentNumber().then(result => console.log(result));
verifyTransaction('123456', 'TRX123456', '+243123456789').then(result => console.log(result));

<?php
// Using PHP with cURL
$apiToken = 'YOUR_API_TOKEN';

// Request a payment number
function requestPaymentNumber($operatorName = null) {
    global $apiToken;
    
    $url = 'https://magoflash.com/api/payment-phone';
    if ($operatorName) {
        $url .= '?operatorName=' . urlencode($operatorName);
    }
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Verify transaction
function verifyTransaction($code, $transactionId, $phoneNumber) {
    global $apiToken;
    
    $ch = curl_init('https://magoflash.com/api/verify-transaction');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'code' => $code,
        'transactionId' => $transactionId,
        'phoneNumber' => $phoneNumber
    ]));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Example usage
$paymentNumber = requestPaymentNumber();
print_r($paymentNumber);

$transaction = verifyTransaction('123456', 'TRX123456', '+243123456789');
print_r($transaction);
?>

Authentication

All API requests must be authenticated using a Bearer token. You can generate API tokens from your merchant dashboard.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://magoflash.com/api/balances

API Reference

Verify Transaction

Verify a transaction using the confirmation code and assign it to your merchant account.

Endpoint

POST /api/verify-transaction

Request Body

{
  "code": "123456",
  "transactionId": "TRX123456",
  "phoneNumber": "+243123456789"
}

Response

{
  "status": "success",
  "code": "SUCCESS",
  "message": "Transaction verified successfully",
  "data": {
    "transactionId": "TRX123456",
    "amount": 100,
    "currency": "USD"
  }
}

Get Balances

Retrieve current balances for all currencies in your merchant account.

Endpoint

GET /api/balances

Response

{
  "status": "success",
  "data": [
    {
      "currency": "USD",
      "amount": 1000.50
    },
    {
      "currency": "EUR",
      "amount": 750.25
    }
  ]
}

Get Payment Phone Number

Retrieve a random remitter phone number for payment. Optionally, you can specify an operator name to get a number from a specific operator.

Endpoint

GET /api/payment-phone

Query Parameters

{
  "operatorName": "string" // Optional
}

Response

{
  "status": "success",
  "data": {
    "phoneNumber": "+243123456789",
    "network": "Operator Name",
    "country": "Country Name"
  }
}

Get Operators

Retrieve a list of all available operators.

Endpoint

GET /api/operators

Response

{
  "status": "success",
  "data": [
    {
      "name": "Operator Name",
      "humanReadable": "Operator Human Readable Name",
      "country": "Country Name",
      "countryCode": "+243",
      "prefixes": ["123", "456"]
    }
  ]
}

Transfer Money

Transfer money between merchant accounts.

Endpoint

POST /api/transfer

Request Body

{
  "receiverEmail": "recipient@example.com",
  "amount": 100,
  "currency": "USD"
}

Response

{
  "status": "success",
  "message": "Money transferred successfully",
  "data": {
    "transactionId": "MGFT123_1234567890_0001",
    "amount": 100,
    "currency": "USD",
    "status": "completed"
  }
}

Error Responses

Common error codes:

• INVALID_INPUT: Missing or invalid request parameters
• RECIPIENT_NOT_FOUND: The recipient email does not exist
• INSUFFICIENT_BALANCE: Not enough balance in the specified currency
• UNSUPPORTED_EXCHANGE: Transfer type not supported

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests.