Request and Response Format

This page provides details on how to structure your requests to the Mopay API and what response formats to expect.

Base URL

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

https://service.mopay-ng.com/?req=your_endpoint

Note: During development, you may use a different base URL provided in your developer dashboard.

HTTP Methods

Mopay API uses standard HTTP methods to perform different operations:

GET

Retrieve resources

Used to retrieve information, such as user profiles, transaction history, or account balances.

POST

Create resources

Used to create new resources, such as user accounts, payment transactions, or service requests.

PUT

Update resources

Used to update existing resources completely, replacing the entire resource.

PATCH

Partial updates

Used to update parts of existing resources, such as updating only a user's name or email.

DELETE

Remove resources

Used to delete resources, such as removing a payment method or canceling a subscription.

Request Format

All requests to the Mopay API should be in JSON format. Set the following headers in your requests:

Content-Type: application/jsonMPY-SECUREKEY: your_public_keyMPY-TIMESTAMP: current_unix_timestampMPY-REQSIGNAL: request_signature

For authenticated endpoints, you must include the HMAC-based authentication headers as described in the Authentication section.

Here's an example of a typical request body:

{
  "user_id": "usr_123456789",
  "amount": 5000,
  "currency": "NGN",
  "description": "Payment for services",
  "reference": "tx_ref_123456789"
}

Response Format

All responses from the Mopay API are in JSON format. Successful responses typically follow this structure:

{
  'REQUEST': {
    'VERSION': '1.0',
    'ACTION': endpoint,
    'STATUS': 'OK'
  },
  'DATA': [... array of data objects ...]
}

Error responses follow this format:

{
  'REQUEST': {
    'VERSION': '1.0',
    'ACTION': endpoint,
    'STATUS': 'FAILED'
  },
  'ERRORS': {
    'CODE': 401,
    'DETAILS': 'Error message (Error code)'
  }
}

Status Codes

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

2xx Success

200 OK: The request was successful.
201 Created: A new resource was successfully created.
202 Accepted: The request has been accepted for processing.
204 No Content: The request was successful, but there is no content to return.

4xx Client Error

400 Bad Request: The request was malformed or contains invalid parameters.
401 Unauthorized: Authentication is required or failed.
403 Forbidden: The authenticated user doesn't have permission to access the resource.
404 Not Found: The requested resource doesn't exist.
422 Unprocessable Entity: The request was well-formed but contains semantic errors.
429 Too Many Requests: Rate limit exceeded.

5xx Server Error

500 Internal Server Error: An unexpected error occurred on the server.
502 Bad Gateway: The server received an invalid response from an upstream server.
503 Service Unavailable: The server is temporarily unavailable, usually due to maintenance.
504 Gateway Timeout: The server timed out waiting for a response from an upstream server.

Pagination

For endpoints that return a list of resources (like transactions or users), the API supports pagination to limit the number of results returned in a single response.

Pagination Parameters

pagination: The unix timestamp of the last item from the current served data.

Example request with pagination:

GET /transactions?page=2&limit=50

Paginated responses include metadata about the pagination:

{
  'REQUEST': {
    'VERSION': '1.0',
    'ACTION': endpoint,
    'STATUS': 'OK'
  },
  'DATA': {
    'result': [... array of data objects ...],
    'pagination': "123456789001"
  }
}