Back to API Reference

Notifications & Messaging Endpoints

These endpoints allow you to manage user notifications, notices, newsletter subscriptions, and location data. All endpoints require authentication with HMAC-based authentication headers (MPY-SECUREKEY, MPY-TIMESTAMP, MPY-REQSIGNAL) as described in the Authentication section unless otherwise specified.

Get User Notices

Retrieve notices for the authenticated user

GET

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

This endpoint retrieves all notices for the authenticated user, including system alerts, security notifications, and account updates. Results are paginated with up to 15 records per page.

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.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesThe format of the request payload

Query Parameters

NameTypeRequiredDescription
pagestringNoPage number for pagination (default: 123456789001)

Request Example

GET /user_notice_fetch?page=1687341045

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_notice_fetch",
    "STATUS": "OK"
  },
  "DATA": {
    "result": [
      {
        "marker": "ntc_123456789",
        "userid": "usr_12345abcde",
        "subject": "Security Update",
        "message": "We have updated our security protocols to better protect your account.",
        "recorded": "1683721042"
      },
      {
        "marker": "ntc_987654321",
        "userid": "usr_12345abcde",
        "subject": "Account Verification Required",
        "message": "Please verify your identity to continue using all features of your account.",
        "recorded": "1683635722"
      }
    ],
    "pagination": "123456789001"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_notice_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_notice_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "response_empty",
    "DETAILS": "We couldn't find any record matching your query (MPS323981728508498)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_notice_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_failed",
    "DETAILS": "Failed to process your request (MPS742330378600148)"
  }
}

Get User Notifications

Retrieve notifications for the authenticated user

GET

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

This endpoint retrieves notifications for a user. By default, it fetches notifications for the authenticated user, but it can also retrieve notifications for a specific user or a specific notification by its marker. Results are ordered by timestamp in descending order (newest first).

Note: The rqtp parameter must be set to specify the type of query. Use "user" to get notifications for a user, or "mk" to get a specific notification by its marker.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesThe format of the request payload

Query Parameters

NameTypeRequiredDescription
rqtpstringYesThe type of notifications to fetch (user, mk, all)
rqvlstringNoValue to filter by (user ID when type is "user" or notification marker when type is "mk"). If omitted when using "user" type, the current authenticated user is used.

Request Example

GET /user_notification_fetch?rqtp=user&rqvl=4xib766n87c9

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_notification_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "ntf_123456789",
      "userid": "usr_12345abcde",
      "token_type": "ExponentPushToken",
      "push_token": "ExponentPushToken[1234567890]",
      "channel_Id": "1234567890",
      "status": "active",
      "recorded": "1684140431"
    },
    {
      "marker": "ntf_987654321",
      "userid": "usr_12345abcde",
      "token_type": "ExponentPushToken",
      "push_token": "ExponentPushToken[1234567890]",
      "channel_Id": "1234567890",
      "status": "active",
      "recorded": "1684060038"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_notification_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "Unauthorized",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_notification_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "ID": "rqtp_required",
    "DETAILS": "Query type is required (MPS175604753956740)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_notification_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "process_error",
    "DETAILS": "Could not process your request (MPS371000199700247)"
  }
}

Create Newsletter Subscription

Subscribe to the Mopay newsletter

GET

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

This endpoint allows users to subscribe to the Mopay newsletter. Authentication is not required. The user must first request a verification code for their email address using the Send Email Verification endpoint, then use that code to confirm their newsletter subscription.

Note: You must first send a verification code to the email address using the Send Email Verification endpoint before subscribing to the newsletter.

Headers

NameValueRequiredDescription
Content-Typeapplication/jsonYesThe format of the request payload

Query Parameters

NameTypeRequiredDescription
emalstringYesEmail address to subscribe to newsletter
codestringYesEmail verification code to confirm subscription

Request Example

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

Body:

{}

Success Response

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

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_newsletter_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "emal_required",
    "DETAILS": "Email address is required (MPS766319234259789)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_newsletter_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "MSG": "code_required",
    "DETAILS": "Email address authentication code is required (MPS180358729739685)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_newsletter_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "MSG": "code_incorrect",
    "DETAILS": "Incorrect email verification code (MPS373783605436057)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_newsletter_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 409,
    "MSG": "already_subscribed",
    "DETAILS": "Oops! It looks like you're already subscribed to our newsletter (MPS441208672333285)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_newsletter_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "MSG": "server_error",
    "DETAILS": "Could not process your request (MPS866561004237563)"
  }
}

Fetch Location Data

Retrieve location data (countries, states, cities)

GET

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

This endpoint retrieves location data including countries, states/provinces, and cities. The rtyp parameter determines which type of location data to fetch. If no parameters are provided, it defaults to returning all location data.

Note: If rtyp is not provided, it defaults to "all" if rqvl is missing or "mk" if rqvl is provided. Results are paginated when the page parameter is included.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesThe format of the request payload

Query Parameters

NameTypeRequiredDescription
rtypstringNoType of location data to fetch (e.g., "countries", "states", "cities")
rqvlstringNoFilter value for the location data, defaults to "false" if not provided
pagestringNoPage number for pagination (default: 123456789001)

Request Example

GET /user_location_fetch?rtyp=countries&rqvl=US&page=1687341045

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_location_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "loc_1234567890",
      "userid": "usr_12345abcde",
      "ip": "192.168.1.1",
      "city": "New York",
      "region": "New York",
      "country": "United States",
      "isp": "Verizon",
      "timeZone": "America/New_York",
      "axis": "1234567890",
      "cntiso": "US",
      "status": "active",
      "recorded": "1687341045"
    },
    {
      "marker": "loc_1234567890",
      "userid": "usr_12345abcde",
      "ip": "192.168.1.1",
      "city": "New York",
      "region": "New York",
      "country": "United States",
      "isp": "Verizon",
      "timeZone": "America/New_York",
      "axis": "1234567890",
      "cntiso": "US",
      "status": "active",
      "recorded": "1687341045"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_location_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "MSG": "rqat_required",
    "DETAILS": "Oops, unauthorised request (MPS613273847085343)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_location_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "MSG": "not_found",
    "DETAILS": "We couldn't find any record matching your query (MPS370159557855160)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_location_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "MSG": "server_error",
    "DETAILS": "Could not process your request"
  }
}