User & Authentication Endpoints

These endpoints handle user registration, authentication, profile management, and account security within the Mopay platform. Developers can implement user sign-up, login, account verification, and profile management using these APIs.

User Registration

POST

Description

This endpoint allows new users to create an account on the Mopay platform. The registration process requires basic information such as first name, last name, email, and password, as well as device information. After successful registration, a verification email is sent to the user's email address and the user is assigned a unique user ID. The response includes an access token that can be used for immediate authentication.

Authentication is not required for this endpoint. You can make requests without providing authentication headers.

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	Format of the request body

Request Body Parameters

Name	Type	Required	Description
fsnm	string	Yes	User's first name
lsnm	string	Yes	User's last name
emal	string	Yes	User's email address
pswd	string	Yes	User's desired password (min: 8 characters, must include uppercase, lowercase, number)
devt	string	Yes	User's device type (e.g., 'Android', 'iOS', 'Web')
devs	string	Yes	User's device serial/unique identifier
devn	string	Yes	User's device name
refx	string	No	Referral code if referred by another user
tktp	string	No	Token type for push notifications
phtk	string	No	Push notification token
chid	string	No	Channel ID for notifications

Request Example

POST /user_profile_create

Body:

{
  "fsnm": "John",
  "lsnm": "Doe",
  "emal": "john.doe@example.com",
  "pswd": "SecureP@ssw0rd",
  "devt": "iOS",
  "devs": "iPhone13-AABBCC123456",
  "devn": "John's iPhone",
  "refx": "REF123456",
  "tktp": "ExponentPushToken",
  "phtk": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "chid": "notification_channel_id"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "h5d5s78nb4d4",
    "userid": "5wh7n78bex4s",
    "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    "pbcKey": "34f5435d54e5f6gt65ef",
    "expires": "312334444323"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "fsnm_required",
    "DETAILS": "User's first name is required (MPS965295426586718)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "lsnm_required",
    "DETAILS": "User's last name is required (MPS161589812874837)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "emal_required",
    "DETAILS": "User's email address is required (MPS256280046845571)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "pswd_required",
    "DETAILS": "User desired password is required (MPS719909317049989)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "devt_required",
    "DETAILS": "User's Device Type is required (MPS707771432691400)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "devs_required",
    "DETAILS": "User's Device Serial is required (MPS973259469176333)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "devn_required",
    "DETAILS": "User's Devices name is required (MPS586226793441740)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Email already registered",
    "DETAILS": "An account with this email already exists (MPS981234567891)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Registration failed",
    "DETAILS": "Unable to complete registration. Please try again later (MPS981234567892)"
  }
}

User Login

POST

Description

This endpoint authenticates a user and creates a new session. Upon successful authentication, it returns an access token for subsequent authenticated requests along with basic user information. Device information is required to associate the login session with a specific device. If provided, notification tokens will be registered for the user to enable push notifications.

Authentication is not required for this endpoint. You can make requests without providing authentication headers.

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	Format of the request body

Request Body Parameters

Name	Type	Required	Description
emal	string	Yes	User's email address
pswd	string	Yes	User's password
dvty	string	Yes	User's device type (e.g., 'Android', 'iOS', 'Web')
dsnm	string	Yes	User's device serial/unique identifier
dvnm	string	No	User's device name
tktp	string	No	Token type for push notifications
phtk	string	No	Push notification token
chid	string	No	Notification channel ID

Request Example

POST /user_profile_login

Body:

{
  "emal": "john.doe@example.com",
  "pswd": "SecureP@ssw0rd",
  "dvty": "iOS",
  "dsnm": "iPhone13-AABBCC123456",
  "dvnm": "John's iPhone",
  "tktp": "FCM",
  "phtk": "fcm-token-example-123456789",
  "chid": "user-notifications-channel"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_login",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "h5d5s78nb4d4",
    "userid": "5wh7n78bex4s",
    "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    "pbcKey": "34f5435d54e5f6gt65ef",
    "expires": "312334444323"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "emal_required",
    "DETAILS": "User's email address is required (MPS215213462776769)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "pswd_required",
    "DETAILS": "User's password is required (MPS344814454485441)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "dvty_required",
    "DETAILS": "User's Device Type is required (MPS245997658188055)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "dsnm_required",
    "DETAILS": "User's Device Serial is required (MPS688014047902334)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Incorrect credentials (MPS695543757087534)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Oops, something went wrong, please try again (MPS914151590642267)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "DETAILS": "Internal server error (MPS217335133363312)"
  }
}

User Logout

Disconnect device from account

GET

Description

This endpoint logs out a user by invalidating their current authentication token. After this call, the token will no longer be valid for any API requests. No additional parameters are required as the user's session information is extracted from the Authorization header.

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

Request Example

GET /user_profile_logout

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_logout",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Operation successful!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_logout",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_logout",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_failed",
    "DETAILS": "Failed to process your request (MPS742330378600148)"
  }
}

Google Login

Authenticate a user with Google credentials

POST

Description

This endpoint allows users to authenticate or register using their Google account. The client application should first complete the Google Sign-In flow to obtain a Google OAuth token, which is then sent to this endpoint along with device information. If the user doesn't exist, a new account will be created automatically using the information from their Google profile. If the user already exists, they will be logged in to their existing account. The response includes user profile information and an authentication token for subsequent API calls.

Authentication is not required for this endpoint. You can make requests without providing authentication headers.

Important: To use this endpoint, your application must be registered with Google and have Google Sign-In configured. The client application is responsible for implementing the Google Sign-In flow to obtain the Google OAuth token.

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	Format of the request body

Request Body Parameters

Name	Type	Required	Description
rqat	string	Yes	Google OAuth token obtained from Google Sign-In
devt	string	Yes	Device type (e.g., "android", "ios", "web")
devs	string	Yes	Device serial number or unique identifier
devn	string	Yes	Device name (e.g., "iPhone 13", "Samsung Galaxy S21")
tktp	string	No	Push notification token type (e.g., "fcm", "apns")
phtk	string	No	Push notification token
chid	string	No	Channel ID for push notifications

Request Example

POST /user_google_login

Body:

{
  "rqat": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFiZDY4NWY1ZThmMzA2MjY...",
  "devt": "android",
  "devs": "a1b2c3d4e5f6g7h8i9j0",
  "devn": "Google Pixel 6",
  "tktp": "fcm",
  "phtk": "fnX2oP8yTKKJ23NFG456...",
  "chid": "user_notifications"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_google_login",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "h5d5s78nb4d4",
    "userid": "5wh7n78bex4s",
    "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    "pbcKey": "34f5435d54e5f6gt65ef",
    "expires": "312334444323"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_google_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_google_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "devt_required",
    "DETAILS": "User's Device Type is required (MPS556270292071835)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_google_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "devs_required",
    "DETAILS": "User's Device Serial is required (MPS684912061767792)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_google_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "devn_required",
    "DETAILS": "User's Devices name is required (MPS785633731881287)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_google_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "request_failure",
    "DETAILS": "Could not process your request (MPS634429297237638)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_google_login",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "unknown_failure",
    "DETAILS": "Oops, something went wrong, please try again (MPS778685379516054)"
  }
}

Get Authentication Info

Retrieve current authentication and session information

GET

Description

This endpoint retrieves detailed information about the user's current authentication status, including session details, permissions, and security events. It can be used to verify the user's authentication status, check token validity, or display authentication information to the user. The response includes information about the authentication type, permissions, token expiration, active sessions, and recent security events.

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

Request Example

GET /user_authentication

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_authentication",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "h5d5s78nb4d4",
    "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    "expires": "312334444323"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_authentication",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Unauthorized",
    "DETAILS": "Invalid or expired token (MPS186244751624519)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_authentication",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Access Denied",
    "DETAILS": "Your account does not have permission to access this resource (MPS675239418596743)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_authentication",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Server Error",
    "DETAILS": "Failed to retrieve authentication information. Please try again (MPS981234567890)"
  }
}

Verify Authentication

Verify the validity of a user's authentication token

GET

Description

This endpoint verifies the validity of a user's authentication token. It's typically used to confirm that a user is properly authenticated and their session is still valid. The endpoint requires the user's authentication token to be passed in the Authorization header and returns a simple success message if the token is valid.

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

Note: This endpoint is used to verify if a token is valid. If the token is invalid or expired, a 401 Unauthorized error will be returned.

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

Request Example

GET /authentication_verify

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "authentication_verify",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Operation successful!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "authentication_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "authentication_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "request_failed",
    "DETAILS": "Could not process your request (MPS634429297237638)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "authentication_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "logout_failed",
    "DETAILS": "Failed to process your request (MPS742330378600148)"
  }
}

Get User Profile

Retrieve authenticated user's profile information

GET

Description

This endpoint retrieves the complete profile information for the currently authenticated user. The profile data includes personal information, account details, and settings. Authentication is required, and the response will contain the profile data for the user associated with the provided access token.

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

Request Example

GET /user_profile_get_info

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_get_info",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "5c4xx7i65u56",
    "username": "johndoe92",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+2348012345678",
    "emailAddress": "john.doe@example.com",
    "phoneVerify": "unverified",
    "emailVerify": "unverified",
    "identVerify": "unverified",
    "balance": 0,
    "rewardTotal": 0,
    "rewardPoint": 0,
    "rewardPackage": "Mopocket Plan",
    "rewardLevel": "starter",
    "rewardValue": 0,
    "passcode": "active",
    "tradeVolume": 0,
    "tradeCounts": 0,
    "referralCount": 0,
    "referralCode": "5c4xx7i65u56",
    "referralBonus": 0,
    "referrerid": "5c4xx7i65u56",
    "activeDate": "2023-01-15",
    "activeTime": "10:10:10",
    "status": "active",
    "recorded": "1673778645212"
  }
}

Possible Error Responses

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

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_get_info",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "User not found",
    "DETAILS": "No data matching your query was found (MPS775873117725199)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_get_info",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Server error",
    "DETAILS": "An unexpected error occurred (MPS981234567895)"
  }
}

Update User Profile

Update authenticated user's profile details

POST

Description

This endpoint allows users to update their profile details. Currently, only first name (fNme) and last name (lNme) updates are supported. The endpoint updates only the fields provided in the request, leaving other fields unchanged. Authentication is required, and the profile updates will be applied to the user associated with the provided access token.

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

Request Body Parameters

Name	Type	Required	Description
fNme	string	No	User's first name
lNme	string	No	User's last name

Request Example

POST /user_profile_update

Body:

{
  "fNme": "John",
  "lNme": "Doe"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_update",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Account details updated successfully!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_update",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Unauthorized",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_update",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "update_failed",
    "DETAILS": "Profile update request failed (MPS540751147468485)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_profile_update",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_error",
    "DETAILS": "Failed to process your request (MPS742330378600148)"
  }
}

Change Password

Change the authenticated user's password

POST

Description

This endpoint allows users to change their account password. The user must provide their current password for verification, along with the new password they wish to set. For security reasons, password changes trigger a notification to the user's email address. The system also checks if the new password has been used before and prevents reuse of recent passwords.

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

Security Note: This endpoint is for changing a password when the user knows their current password. For password reset functionality (when a user has forgotten their password), use the password reset endpoints.

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

Request Body Parameters

Name	Type	Required	Description
pswd	string	Yes	User's current password
npwd	string	Yes	New password (min: 8 characters, must include uppercase, lowercase, number)

Request Example

POST /user_password_change

Body:

{
  "pswd": "OldSecureP@ss123",
  "npwd": "NewSecureP@ss456"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_change",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Operation successful!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_change",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "pswd_required",
    "DETAILS": "Current password is required (MPS844383750075256)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_change",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "npwd_required",
    "DETAILS": "New password is required (MPS129864042662209)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_change",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "test_account",
    "DETAILS": "Oops, password change is not allowed on a test account (MPS165949922662582)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_change",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "password_error",
    "DETAILS": "Oops, you've used this password before please choose another password (MPS568083884765401)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_change",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Unauthorized",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_change",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_error",
    "DETAILS": "Could not process your request (MPS502489419386934)"
  }
}

Reset Password

Reset a user's password using a verification code

POST

Description

This endpoint allows users to reset their password by providing their email address, a new password, and a verification code previously sent to their email. The system verifies the code, ensures the new password hasn't been used before, and updates the user's credentials. After a successful password reset, a notification is sent to the user's email to confirm the change and alert them if they didn't initiate the action.

Authentication is not required for this endpoint. You can make requests without providing authentication headers.

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	Format of the request body

Request Parameters

Name	Type	Required	Description
emal	string	Yes	User's email address
pswd	string	Yes	New desired password
code	string	Yes	Verification code received via email

Request Example

POST /user_password_reset

Body:

{
  "emal": "user@example.com",
  "pswd": "NewSecurePassword123!",
  "code": "123456"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_reset",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Operation successful!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_reset",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "ID": "emal_required",
    "DETAILS": "User's email address is required (MPS789420790804415)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_reset",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "ID": "pswd_required",
    "DETAILS": "New desired password is required (MPS713742198110756)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_reset",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "ID": "code_required",
    "DETAILS": "Verification code is required (MPS142009014593553)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_reset",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 403,
    "DETAILS": "Oops, password change is not allowed on a test account (MPS155127913258975)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_reset",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Oops, you've used this password before please choose another password (MPS358864337510586)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_reset",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Invalid email address verification code (MPS718806430115796)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_password_reset",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "Sorry, the provided email address is not linked to any account in our system (MPS640415463924584)"
  }
}

Send Email Verification

Send a verification code to an email address

GET

Description

This endpoint sends a verification code to the specified email address to verify email ownership. Email verification is an important security measure that confirms users have access to the email address. The verification code is sent to the specified email address and is valid for 1 hour. Users should then use the Verify Email Code endpoint to complete the verification process.

Authentication is not required for this endpoint. You can make requests without providing authentication headers.

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	Format of the request body

Query Parameters

Name	Type	Required	Description
emal	string	Yes	Email address to send verification code to

Request Example

GET /user_email_verify_send?emal=john.doe@example.com

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify_send",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Verification code has been sent to email!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify_send",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify_send",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "emal_required",
    "DETAILS": "Email address is required (MPS559098854394794)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify_send",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_failed",
    "DETAILS": "Could not process your request (MPS395655299976223)"
  }
}

Verify Email Code

Verify an email address using a verification code

GET

Description

This endpoint verifies an email address using the verification code that was sent to that email address. The user must first request a verification code using the Send Email Verification endpoint. After receiving the verification code via email, the user submits the code through this endpoint to complete the verification process. Once verified, the response confirms that the verification code is valid.

Authentication is not required for this endpoint. You can make requests without providing authentication headers.

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	Format of the request body

Query Parameters

Name	Type	Required	Description
emal	string	Yes	Email address to verify
code	string	Yes	Verification code received in email

Request Example

GET /user_email_verify?emal=john.doe@example.com&code=123456

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Verification code is valid!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "emal_required",
    "DETAILS": "Email address is required (MPS851193072288052)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "code_required",
    "DETAILS": "Verification code is required (MPS406738327638000)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "code_invalid",
    "DETAILS": "Incorrect verification code (MPS718869923496012)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_email_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_failed",
    "DETAILS": "Failed to process your request (MPS742330378600148)"
  }
}

Update Email

Updates or adds a new email address to the user account after verification

GET

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
Content-Type	application/json	Yes	Format of the request body

Body Parameters

Name	Type	Required	Description
emal	string	Yes	New email address to be added to the user account
code	string	Yes	Verification code received from email verification process

Request Example

GET /user_email_update?emal=newemail@example.com&code=123456

Headers:

{
  "Content-Type": "application/json"
}

Success Response

{
  "DATA": {
    "COMMENT": "Email address was added successfully!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "emal": "missing"
  },
  "ERRORS": {
    "ID": "emal_required",
    "DETAILS": "Email address is required (MPS233071713869849)"
  }
}

{
  "REQUEST": {
    "code": "missing"
  },
  "ERRORS": {
    "ID": "code_required",
    "DETAILS": "Verification code is required (MPS105055715490622)"
  }
}

{
  "REQUEST": {
    "emal": "test@example.com",
    "code": "123456"
  },
  "ERRORS": {
    "DETAILS": "Incorrect email verification code (MPS766739965311989)"
  }
}

{
  "REQUEST": {
    "emal": "existing@example.com",
    "code": "123456"
  },
  "ERRORS": {
    "DETAILS": "Email address is already linked to a Mopay account (MPS404732042150771)"
  }
}

{
  "REQUEST": {
    "emal": "test@example.com",
    "code": "123456"
  },
  "ERRORS": {
    "DETAILS": "Could not process your request (MPS838046713838415)"
  }
}

Implementation Notes

The user must have previously verified their original email before updating to a new one
A verification code must be obtained for the current email address before updating
The system checks if the new email is already linked to another account
Once successful, a notification is sent to the user confirming the email change

Confirm Email Address

Confirms a user's email address using a verification code

GET

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
Content-Type	application/json	Yes	Format of the request body

Query Parameters

Name	Type	Required	Description
code	string	Yes	Verification code received to confirm the email address

Request Example

GET /user_email_confirm?code=123456

Headers:

{
  "Content-Type": "application/json"
}

Success Response

{
  "DATA": {
    "COMMENT": "Operation successful!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "code": "missing"
  },
  "ERRORS": {
    "ID": "code_required",
    "DETAILS": "Verification code is required (MPS760718799531076)"
  }
}

{
  "REQUEST": {
    "code": "123456"
  },
  "ERRORS": {
    "DETAILS": "Incorrect verification code (MPS780592154384893)"
  }
}

Implementation Notes

This endpoint completes the email verification process for a user account
The verification code must be obtained through the email verification process
Once verified, the user's email status is marked as 'verified' in the system
A verified email is required for certain account operations and security features

Get Login Activity

Retrieve a user's login activity history

GET

Description

This endpoint retrieves a history of the user's login activities, including successful and expired login sessions. It provides details such as login time, device information, location, IP address, and session status. This information can be useful for security monitoring, allowing users to identify unauthorized access attempts or suspicious activities on their account.

Note: The pagination parameter expects a timestamp from the last record of the previous page. To get the next page, use the "pagination" value from the response. Up to 15 records are returned per page.

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
page	string	No	Page number for pagination (default: 123456789001)

Request Example

GET /user_login_fetch?page=1687341045

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_login_fetch",
    "STATUS": "OK"
  },
  "DATA": {
    "result": [
      {
        "marker": "login_12345abcde",
        "userid": "usr_12345abcde",
        "authid": "auth_12345abcde",
        "ipaddx": "192.168.1.1",
        "recorded": "1687427445"
      },
      {
        "marker": "login_987654321",
        "userid": "usr_12345abcde",
        "authid": "auth_987654321",
        "ipaddx": "192.168.1.2",
        "recorded": "1687341045"
      }
    ],
    "pagination": "123456789001"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_login_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_login_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "response_empty",
    "DETAILS": "We couldn't find any record matching your query (MPS753329501340356)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_login_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_failed",
    "DETAILS": "Failed to process your request (MPS742330378600148)"
  }
}

Create Passcode

Create a security passcode for the authenticated user

POST

Description

This endpoint allows users to create a security passcode for their account. The passcode serves as an additional security layer for sensitive operations within the application. A user can only have one passcode at a time, and the passcode is stored securely with encryption.

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

Security Note: The passcode should be kept confidential and not shared with anyone. A notification will be sent to the user's email address when a passcode is successfully created.

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

Request Body Parameters

Name	Type	Required	Description
psscd	string	Yes	User's security passcode

Request Example

POST /user_passcode_create

Body:

{
  "psscd": "123456"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_create",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Security passcode was set successfully!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "psscd_required",
    "DETAILS": "User security passcode is required (MPS26172383223738322)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "User already set security passcode (MPS261734962719274)"
  }
}

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

Update Passcode

Update the security passcode for the authenticated user

POST

Description

This endpoint allows users to update their existing security passcode. For security reasons, the user must verify their identity with an email verification code before the passcode can be updated. A notification will be sent to the user upon a successful passcode update.

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

Security Note: Updating a passcode requires email verification to ensure the request is legitimate. The email verification code should be requested separately before calling this endpoint.

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

Request Body Parameters

Name	Type	Required	Description
vcode	string	Yes	Email verification code
psscd	string	Yes	New security passcode

Request Example

POST /user_passcode_update

Body:

{
  "vcode": "123456",
  "psscd": "654321"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_update",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Security passcode was updated successfully!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_update",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "vcode_required",
    "DETAILS": "Email verification code is required (MPS233071713869849)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_update",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "psscd_required",
    "DETAILS": "New users security passcode is required (MPS105055715490622)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_update",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Invalid email verification code (MPS2819282242763827)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_update",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "User haven't set security passcode (MPS286432628643672)"
  }
}

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

Verify Passcode

Verify the security passcode of the authenticated user

POST

Description

This endpoint verifies that the provided passcode matches the security passcode stored for the authenticated user. This verification is often required before performing sensitive operations or accessing protected resources within the application.

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

Usage Note: This endpoint can be used to verify a user's passcode before allowing them to perform sensitive operations like changing account settings, making payments, or accessing confidential information.

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

Request Body Parameters

Name	Type	Required	Description
psscd	string	Yes	User's security passcode

Request Example

POST /user_passcode_verify

Body:

{
  "psscd": "123456"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_verify",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Security passcode verified!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "psscd_required",
    "DETAILS": "Security passcode is required (MPS27456392845643)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_passcode_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Incorrect security passcode (MPS274563552645678)"
  }
}

Send Authentication Code

Send a verification code to the authenticated user's email address

GET

Description

This endpoint sends an authentication verification code to the email address associated with the authenticated user's account. Unlike the Send Email Verification endpoint that requires specifying an email address, this endpoint automatically retrieves the user's email from their account profile and sends the code to that address. The verification code is valid for 1 hour and can be used for various authentication purposes where additional verification is required.

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
Content-Type	application/json	Yes	Format of the request body

Request Example

GET /user_send_auth_code

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_send_auth_code",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Verification code has been sent to email!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_send_auth_code",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_send_auth_code",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_failed",
    "DETAILS": "Could not process your request (MPS376484706533177)"
  }
}

Get Location Details

Retrieve detailed information about a specific location

GET

Description

This endpoint retrieves detailed information about a specific location based on the provided location ID. The returned data includes comprehensive geographic and network information for the location.

Each location record includes the following details:

marker: Unique identifier for the location record
userid: User identifier associated with the location data
ip: IP address associated with the location
city: City name
region: Region or state
country: Country name
isp: Internet Service Provider for the location
timeZone: Time zone of the location
axis: Geographic coordinates (latitude,longitude)
cntiso: Country ISO code
status: Status of the location record (active/inactive)
recorded: Timestamp when the location was recorded

This location data is useful for displaying location details in user interfaces, for security monitoring, and for validating location information before processing user requests.

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
Content-Type	application/json	Yes	Format of the request body

Query Parameters

Name	Type	Required	Description
lkid	string	Yes	The location ID to retrieve details for

Request Example

GET /user_location_get?lkid=loc_123456

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_location_get",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "loc_123456",
    "userid": "usr_12345abcde",
    "ip": "192.168.1.1",
    "city": "New York",
    "region": "New York State",
    "country": "United States",
    "isp": "Verizon Communications",
    "timeZone": "America/New_York",
    "axis": "40.7128,-74.0060",
    "cntiso": "US",
    "status": "active",
    "recorded": "1686744645"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_location_get",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

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

Claim Incentive Reward

Claim available incentive rewards for the authenticated user

POST

Description

This endpoint allows authenticated users to claim any available incentive rewards or bonuses associated with their account. Incentive rewards may be offered for various user actions such as account creation, completing profile information, referrals, or promotional campaigns. The API checks if the user has any unclaimed rewards and processes the claim, adding the relevant benefits to the user's account. Only one claim can be processed at a time.

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
Content-Type	application/json	Yes	Format of the request body

Request Example

POST /user_incentives_claim

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_incentives_claim",
    "STATUS": "OK"
  },
  "DATA": {
    "COMMENT": "Incentive reward claimed successfully!"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_incentives_claim",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_incentives_claim",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "MSG": "process_failed",
    "DETAILS": "Could not process your request (MPS291726492716252)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_incentives_claim",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 403,
    "MSG": "no_rewards_available",
    "DETAILS": "No available rewards to claim at this time"
  }
}

Fetch Incentive Rewards

Retrieve the user's incentive rewards and claim history

GET

Description

This endpoint fetches information about a user's incentive rewards. Results can be filtered by various parameters such as marker ID, user ID, or reward package.

Each reward record includes the following details:

marker: Unique identifier for the reward record
userid: User identifier associated with the reward
package: The reward package or program name
points: Number of points accumulated in the reward program
rewards: Monetary value of the rewards (in default currency)
recorded: Timestamp when the reward record was created

This data is useful for displaying available rewards to users, tracking reward program participation, and calculating benefits available to users.

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 reward claims to fetch (mk, all, user, package)
rqvl	string	No	Search value corresponding to the rqtp. Default: "false"
page	string	No	Page number for pagination. Default: "false"

Request Example

GET /user_incentives_fetch?rqtp=user&rqvl=usr_12345abcde

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_incentives_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "rwc_12345abcde",
      "userid": "usr_12345abcde",
      "package": "welcome_package",
      "points": 500,
      "rewards": 50,
      "recorded": "1686744645"
    },
    {
      "marker": "rwc_67890fghij",
      "userid": "usr_12345abcde",
      "package": "referral_program",
      "points": 250,
      "rewards": 25,
      "recorded": "1686833450"
    }
  ]
}

Possible Error Responses

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

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

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_incentives_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Unsupported request type (MPS2817265252918265)"
  }
}

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_incentives_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "No data matching your query was found (MPS208265821826256)"
  }
}