File Management Endpoints

These endpoints allow you to upload, fetch, and delete files in the Mopay system. All endpoints require authentication with HMAC-based authentication headers (MPY-SECUREKEY, MPY-TIMESTAMP, MPY-REQSIGNAL) as described in the Authentication section.

Upload File

Upload a file to the Mopay system

POST

Description

This endpoint allows users to upload files to the Mopay platform. Files can be stored in the user's directory (default) or in a system directory if specified.

Files are processed asynchronously and given a unique marker ID. The response includes details about the file, including its size, type, and URL paths.

Supported File Types: Images (jpg, jpeg, png, gif), Documents (pdf, doc, docx, xls, xlsx, csv, txt), and other common formats.

Maximum File Size: 10MB

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

Name	Value	Required	Description
MPY-SECUREKEY	{public_key}	Yes	Your public key obtained during login/registration
MPY-TIMESTAMP	{unix_timestamp}	Yes	Current unix timestamp in seconds
MPY-REQSIGNAL	{request_signature}	Yes	HMAC-SHA512 signature of the request
Content-Type	application/json	Yes	User's access token
Content-Type	multipart/form-data	Yes	Format of the request (must be multipart/form-data for file uploads)

Body Parameters

Name	Type	Required	Description
file	File	Yes	The file to upload
sysdrn	string	No	System directory for file storage (omit to use user's directory)

Request Example

File uploads must use multipart/form-data encoding

Request Example

POST /core_file_upload

Body:

{
  "file": "(binary file data)",
  "sysdrn": "system_dir"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_upload",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "fil_123456789abcdef",
    "userid": "usr_987654321abcdef",
    "fileName": "profile.jpg",
    "fileType": "image/jpeg",
    "fileSize": 102400,
    "filePath": "https://assets.mopay-ng.com/uploads/usr_987654321abcdef/123456789.jpg",
    "localUrl": "/uploads/usr_987654321abcdef/123456789.jpg",
    "fileMime": "jpg",
    "status": "active",
    "recorded": "1625846400"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_upload",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_upload",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "No file was uploaded (MPS578334882826769)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_upload",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Extension not allowed: script.php (SNN269949725001339)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_upload",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 413,
    "DETAILS": "File size exceeds limit: large_image.jpg (SNN465735427658138)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_upload",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "DETAILS": "Could not process your request (MPS371304906109676)"
  }
}

Fetch Files

Retrieve uploaded files information

GET

Description

This endpoint allows users to retrieve information about files that have been uploaded to the Mopay platform. Files can be fetched by user ID (to get all files for a user) or by file marker/ID (to get a specific file).

When fetching files by user ID, the response includes an array of file objects with pagination information for retrieving additional pages.

When fetching a file by marker/ID, the response includes a single file object with all its details.

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

Name	Value	Required	Description
MPY-SECUREKEY	{public_key}	Yes	Your public key obtained during login/registration
MPY-TIMESTAMP	{unix_timestamp}	Yes	Current unix timestamp in seconds
MPY-REQSIGNAL	{request_signature}	Yes	HMAC-SHA512 signature of the request
Content-Type	application/json	Yes	Format of the request body

Query Parameters

Name	Type	Required	Description
rqtp	string	Yes	The type of files to fetch (user, mk, all)
rqvl	string	No	Value corresponding to the request type (user ID or file ID). Default: current user
page	string	No	Page number for pagination (default: 123456789001)

Example Requests

Fetch files by user ID

Request Example

GET /core_file_fetch?rqtp=user

Fetch a specific file by marker/ID

Request Example

GET /core_file_fetch?rqtp=mk&rqvl=fil_123456789abcdef

Fetch with pagination

Request Example

GET /core_file_fetch?rqtp=user&page=1625760000

Example Responses

Fetch by user ID (multiple files)

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_fetch",
    "STATUS": "OK"
  },
  "DATA": {
    "result": [
      {
        "marker": "fil_123456789abcdef",
        "userid": "usr_987654321abcdef",
        "fileName": "profile.jpg",
        "fileType": "image/jpeg",
        "fileSize": 102400,
        "filePath": "https://assets.mopay-ng.com/uploads/usr_987654321abcdef/123456789.jpg",
        "localUrl": "/uploads/usr_987654321abcdef/123456789.jpg",
        "fileMime": "jpg",
        "status": "active",
        "recorded": "1625846400"
      },
      {
        "marker": "fil_234567890abcdef",
        "userid": "usr_987654321abcdef",
        "fileName": "document.pdf",
        "fileType": "application/pdf",
        "fileSize": 512000,
        "filePath": "https://assets.mopay-ng.com/uploads/usr_987654321abcdef/234567890.pdf",
        "localUrl": "/uploads/usr_987654321abcdef/234567890.pdf",
        "fileMime": "pdf",
        "status": "active",
        "recorded": "1625760000"
      }
    ],
    "pagination": "123456789001"
  }
}

Fetch by file marker/ID (single file)

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_fetch",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "fil_123456789abcdef",
    "userid": "usr_987654321abcdef",
    "fileName": "profile.jpg",
    "fileType": "image/jpeg",
    "fileSize": 102400,
    "filePath": "https://assets.mopay-ng.com/uploads/usr_987654321abcdef/123456789.jpg",
    "localUrl": "/uploads/usr_987654321abcdef/123456789.jpg",
    "fileMime": "jpg",
    "status": "active",
    "recorded": "1625846400"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Request type is required (MPS312632732612723)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "We couldn't find any record matching your query (MPS135910748259220)"
  }
}

Delete File

Remove a file from the user's account

GET

Description

This endpoint allows users to delete files they previously uploaded to the Mopay platform. The file is marked as deleted in the database and physically removed from storage.

Once a file is deleted, it cannot be recovered. The deletion is permanent.

Users can only delete files that they own unless they have administrative privileges.

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

Name	Value	Required	Description
MPY-SECUREKEY	{public_key}	Yes	Your public key obtained during login/registration
MPY-TIMESTAMP	{unix_timestamp}	Yes	Current unix timestamp in seconds
MPY-REQSIGNAL	{request_signature}	Yes	HMAC-SHA512 signature of the request
Content-Type	application/json	Yes	Format of the request body

Query Parameters

Name	Type	Required	Description
fxid	string	Yes	File marker/tracking ID to delete

Request Example

GET /core_file_delete?fxid=fil_123456789abcdef

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_delete",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "File was deleted successfully!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_delete",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_delete",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "fxid_required",
    "CODE": 400,
    "DETAILS": "File tracking ID is required (MPS285354050631785)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_delete",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 403,
    "DETAILS": "You don't have permission to access this file (MPS361582741945612)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_delete",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "File not found (MPS492761548932761)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "core_file_delete",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "DETAILS": "Could not process your request (MPS150590020345111)"
  }
}