Authentication

The Mopay API uses HMAC-based authentication with cryptographic signatures. This secure authentication method requires signing each request with your secret key to ensure data integrity and authenticity.

Obtaining Your API Key and Secret

Your public and secret keys are automatically issued when you register or login to the Mopay platform. You do not need to generate these credentials manually.

The response from the user_profile_create and user_profile_login endpoints will include your pbcKey (public key) and secret (private key) that you should securely store and use for subsequent API requests.

Authentication Headers

All authenticated requests to the Mopay API must include the following headers:

Required Headers

MPY-SECUREKEY: your_public_key

The secure key (also known as public key) obtained during login/registration

MPY-TIMESTAMP: current_unix_timestamp

Current unix timestamp in seconds

MPY-REQSIGNAL: request_signature

HMAC-SHA512 signature of the request

Keep your credentials secure and never share them in publicly accessible areas.

Generating Request Signatures

Each request to a protected endpoint must be signed using your secret key (private key). The signature is created by:

Creating a JSON object containing the current timestamp: {"timestamp": "current_timestamp"}
Generating an HMAC-SHA512 hash of this JSON string using your secret key (private key)
Converting the resulting hash to a hexadecimal string

Signature Generation Examples

JavaScript code snippet

const crypto = require('crypto');

// Your secret key from Mopay (received during login/registration)
const publicKey = 'your_public_key';
const secretKey = 'your_secret_key';

// Current timestamp
const timestamp = Math.floor(Date.now() / 1000).toString();

// Create timestamp object
const timestampObj = { timestamp };

// Generate signature
const signature = crypto
  .createHmac('sha512', secretKey)
  .update(JSON.stringify(timestampObj))
  .digest('hex');

// Use these in your API request headers
const headers = {
  'MPY-SECUREKEY': publicKey,
  'MPY-TIMESTAMP': timestamp,
  'MPY-REQSIGNAL': signature,
  'Content-Type': 'application/json'
};

// Example usage with fetch API
const makeRequest = async () => {
  try {
    const response = await fetch('https://service.mopay-ng.com/?req=your_endpoint', {
      method: 'POST', // or 'GET', etc.
      headers: headers,
      body: JSON.stringify({
        // Your request data here
      })
    });
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error:', error);
  }
};

// Alternative: Example usage with axios
/*
const axios = require('axios');

axios({
  method: 'post', // or 'get', etc.
  url: 'https://service.mopay-ng.com/?req=your_endpoint',
  headers: headers,
  data: {
    // Your request data here
  }
})
.then(response => console.log(response.data))
.catch(error => console.error('Error:', error));
*/

Python code snippet

import hmac
import hashlib
import json
import time
import requests

# Your secret key from Mopay (received during login/registration)
public_key = 'your_public_key'
secret_key = 'your_secret_key'

# Current timestamp
timestamp = str(int(time.time()))

# Create timestamp object
timestamp_obj = {"timestamp": timestamp}

# Generate signature
signature = hmac.new(
    secret_key.encode('utf-8'),
    json.dumps(timestamp_obj).encode('utf-8'),
    hashlib.sha512
).hexdigest()

# Use these in your API request headers
headers = {
    'MPY-SECUREKEY': public_key,
    'MPY-TIMESTAMP': timestamp,
    'MPY-REQSIGNAL': signature,
    'Content-Type': 'application/json'
}

# Example usage with requests library
try:
    response = requests.post(
        'https://service.mopay-ng.com/?req=your_endpoint',
        headers=headers,
        json={
            # Your request data here
        }
    )
    response.raise_for_status()  # Raise exception for 4XX/5XX status codes
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"Error making request: {e}")

PHP code snippet

<?php
// Your keys from Mopay (received during login/registration)
$public_key = 'your_public_key';
$secret_key = 'your_secret_key';

// Current timestamp
$timestamp = time();

// Create timestamp object
$timestamp_obj = json_encode(['timestamp' => (string)$timestamp]);

// Generate signature
$signature = hash_hmac('sha512', $timestamp_obj, $secret_key);

// Use these in your API request headers
$headers = [
    'MPY-SECUREKEY' => $public_key,
    'MPY-TIMESTAMP' => (string)$timestamp,
    'MPY-REQSIGNAL' => $signature
];

// Example usage with cURL
$ch = curl_init('https://service.mopay-ng.com/?req=your_endpoint');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'MPY-SECUREKEY: ' . $public_key,
    'MPY-TIMESTAMP: ' . $timestamp,
    'MPY-REQSIGNAL: ' . $signature,
    'Content-Type: application/json'
]);
// Add request body if needed
// curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request_data));

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

Authentication Flow

The Mopay API uses a secure authentication process that verifies both the identity of the requester and the integrity of the request:

Obtain authentication credentials: Register or login to receive both your public and private keys automatically.
Generate request signature: For each request, create an HMAC-SHA512 signature using your secret key (private key) and the request timestamp.
Send Authenticated Request: Include your public key, timestamp, and signature in the request headers.
Server Verification: The server validates your public key, recreates the signature using the stored secret key (private key), and compares it with your provided signature.
Access Granted: If the signatures match and the token isn't expired, access is granted to the requested resource.
Note: Its important to note that the secret key is used to generate the signature but the public key is used to identify the user and verify the signature.

Security Features

Signatures are verified using constant-time comparison to prevent timing attacks
Tokens have 10 minutes expiration times to limit the potential damage from compromised credentials
Each request requires a unique signature based on the timestamp
The system validates that the user associated with the API key exists and is active

Error Handling

When authentication fails, the API will return appropriate error responses with HTTP status codes.

401 Unauthorized

Returned when authentication credentials are missing or invalid.

{
  'REQUEST': {
    'VERSION': '1.0',
    'ACTION': endpoint,
    'STATUS': 'FAILED'
  },
  'ERRORS': {
    'CODE': 401,
    'ID': "emal_required",
    'DETAILS': 'Access Denied (MPS921322358721345)'
  }
}

401 Forbidden

Returned when the request signature is invalid or expired.

{
  'REQUEST': {
    'VERSION': '1.0',
    'ACTION': endpoint,
    'STATUS': 'FAILED'
  },
  'ERRORS': {
    'CODE': 401,
    'ID': "emal_required",
    'DETAILS': 'Access Forbidden (MPS772132456621234)'
  }
}