Back to API Reference

Wallet & Payments Endpoints

These endpoints handle wallet operations, payment processing, and financial transactions within the Mopay platform. Users can check their wallet balance, view transaction history, fund their wallet, transfer funds to other users, and pay bills using their wallet balance. All wallet endpoints require user authentication via the Authorization header.

Get Wallet Info

Retrieve the current balance and information of the user's wallet

GET

Description

This endpoint retrieves the current wallet information for the authenticated user including balance, wallet ID, owner ID, and recording timestamp. This is useful for displaying the current balance to users and for checking wallet status before transactions.

The wallet information is retrieved directly from the user's wallet record in the database and provides real-time balance information. The endpoint doesn't require any additional parameters beyond authentication.

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

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/jsonYesFormat of the request body

Request Example

GET /user_wallet_get_info

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_get_info",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "wlt_12345abcde",
    "owner": "usr_67890fghij",
    "balance": 1250.75,
    "recorded": "1686744645"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_get_info",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_get_info",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "We couldn't find any record matching your query (MPS464882498547661)"
  }
}

Get Wallet History

Retrieve the transaction history of a user's wallet

GET

Description

This endpoint fetches the user's wallet transaction history including deposits, transfers, and other wallet activities. Results can be filtered by marker ID, owner ID, or transaction ID.

Each transaction record includes details such as transaction type (credit/debit), amount, reference ID, note, and timestamp. This information is useful for building transaction history views and for reconciliation purposes.

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

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/jsonYesFormat of the request body

Query Parameters

NameTypeRequiredDescription
rqtpstringYesThe type of wallet history to fetch (transaction, owner, mk, all)
rqvlstringNoSearch value corresponding to the rqtp (marker ID, owner ID, or transaction ID). Default: "false"
pagestringNoPage number for pagination (default: 123456789001)

Request Example

GET /user_wallet_history?rqtp=owner&rqvl=usr_67890fghij

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_history",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "wlth_12345abcde",
      "owner": "usr_12345abcde",
      "trnxid": "trx_12345abcde",
      "amount": 250,
      "balance": 250,
      "pxtype": "credit",
      "pxnote": "Fund transfer from John Doe",
      "recorded": "1686744645"
    },
    {
      "marker": "wlth_67890fghij",
      "owner": "usr_67890fghij",
      "trnxid": "trx_67890fghij",
      "amount": -100,
      "balance": 150,
      "pxtype": "debit",
      "pxnote": "Fund transfer to Jane Smith",
      "recorded": "1686833450"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_history",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_history",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Request type is required (MPS984220955541217)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_history",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Unsupported request type (MPS426580287835389)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_history",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "We are unable to find data matching your request (MPS556849043866889)"
  }
}

Create Deposit Order

Create a new wallet deposit order

POST

Description

This endpoint creates a new deposit order to fund the user's wallet. The order is initially created with a "pending" status, and the user will need to complete the payment through one of the available payment methods to fulfill the deposit.

Once created, the deposit order will generate a unique reference that can be used to track the payment. The deposit order has an expiration time, after which it will no longer be valid for payment.

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

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/jsonYesFormat of the request body

Request Body Parameters

NameTypeRequiredDescription
amountnumberYesAmount to deposit into the wallet

Request Example

POST /user_deposit_order_create

Body:

{
  "amount": 5000
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_deposit_order_create",
    "STATUS": "OK"
  },
  "DATA": {
    "marker": "wxdp_12345abcde",
    "accountNumber": "1234567890",
    "accountName": "John Doe",
    "bankName": "Access Bank",
    "expires": "1687442415112",
    "amount": "5,000 Naira",
    "pxamount": 5000,
    "currency": "Nigeria Naira",
    "recorded": "1687442415"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_deposit_order_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_deposit_order_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "amount_required",
    "CODE": 400,
    "DETAILS": "Credit order amount is required (MPS884042942369524)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_deposit_order_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "DETAILS": "Could not process your request (MPS928416586413961)"
  }
}

Fetch Deposit Orders

Retrieve list of deposit orders created by the user

GET

Description

This endpoint fetches a list of deposit orders created by the authenticated user. Each deposit record includes the order amount, status, reference number, and timestamp.

The deposits are returned in reverse chronological order, with the most recent appearing first. Each deposit order will have a status that indicates its current state (e.g., "pending", "completed", "failed", "expired").

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

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/jsonYesFormat of the request body

Query Parameters

NameTypeRequiredDescription
rqtpstringYesThe type of deposit history to fetch (user, status, mk, all)
rqvlstringNoSearch value corresponding to the rqtp (marker ID, owner ID, or User ID). Default: "false"
pagestringNoPage number for pagination (default: 123456789001)

Request Example

GET /user_deposit_order_fetch

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_deposit_order_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "wxdp_12345abcde",
      "userid": "usr_12345abcde",
      "ax_bank": "Access Bank",
      "ax_name": "John Doe",
      "ax_amount": 5000,
      "ax_number": "1234567890",
      "ax_expire": "1687442415112",
      "status": "pending",
      "recorded": "1687442415"
    },
    {
      "marker": "wxdp_67890fghij",
      "userid": "usr_67890fghij",
      "ax_bank": "Access Bank",
      "ax_name": "Jane Smith",
      "ax_amount": 10000,
      "ax_number": "1234567890",
      "ax_expire": "1687442415112",
      "status": "completed",
      "recorded": "1687356015"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_deposit_order_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_deposit_order_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "No data matching your query was found (MPS384532812704070)"
  }
}

Transfer Funds

Transfer funds from user's wallet to another user

POST

Description

This endpoint allows users to transfer funds from their wallet to another user's wallet on the platform. The transfer requires the recipient's email address and the amount to transfer. Once completed, the funds are immediately available in the recipient's wallet. The sender's wallet balance is updated to reflect the transfer.

The minimum transfer amount is ₦50.00. Users must have sufficient balance in their wallet to complete the transfer. Both the sender and receiver will receive notifications about the transfer.

The response includes a success message and a transaction ID that can be used to trace the transfer.

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

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/jsonYesFormat of the request body

Request Body Parameters

NameTypeRequiredDescription
emailstringYesRecipient's email address
amountnumberYesAmount to transfer
messgestringNoOptional message or note for the transfer

Request Example

POST /user_transfer_create

Body:

{
  "email": "recipient@example.com",
  "amount": 200,
  "messge": "Payment for services"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_create",
    "STATUS": "OK"
  },
  "DATA": {
    "message": "Transfer of 200.00 Naira to recipient@example.com was successful",
    "transact": "wxtr_12345abcde"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "email_required",
    "CODE": 400,
    "DETAILS": "Recipient email address is required (MPS884042942369525)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "amount_required",
    "CODE": 400,
    "DETAILS": "Transfer amount is required (MPS884042942369526)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Recipient with this email address not found (MPS361230644407623)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "You cannot transfer funds to yourself (MPS361230608447623)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Insufficient funds to complete this transfer (MPS361230608407693)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_create",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "DETAILS": "Could not process your request (MPS928416586413962)"
  }
}

Fetch Transfers

Retrieve list of transfers made by the user

GET

Description

This endpoint fetches a list of transfers made by the authenticated user. The response includes all transfers initiated by the user, regardless of the recipient. Each transfer record includes details about the amount, recipient email, transfer note, status, and timestamp.

The transfers are returned in reverse chronological order, with the most recent transfers appearing first. Optional pagination is available through the page parameter.

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

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/jsonYesFormat of the request body

Query Parameters

NameTypeRequiredDescription
rqtpstringYesThe type of wallet transfer history to fetch (sender, receiver, mk, all)
rqvlstringNoSearch value corresponding to the rqtp (marker ID, owner ID, or User ID). Default: "false"
pagestringNoPage number for pagination (default: 123456789001)

Request Example

GET /user_transfer_fetch

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "wxtr_12345abcde",
      "userid": "usr_67890fghij",
      "receiver": "usr_12345klmno",
      "email": "recipient@example.com",
      "amount": 200,
      "rqnote": "Payment for services",
      "status": "complete",
      "recorded": "1687442415"
    },
    {
      "marker": "wxtr_67890fghij",
      "userid": "usr_67890fghij",
      "receiver": "usr_67890pqrst",
      "email": "another@example.com",
      "amount": 350,
      "rqnote": "Reimbursement",
      "status": "complete",
      "recorded": "1687356015"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "No data matching your query was found (MPS384532812704071)"
  }
}

Verify Transfer Recipient

Verify if a recipient exists before initiating a transfer using email or reference ID

GET

Description

This endpoint checks if a user exists and can receive wallet transfers. You can verify a recipient either by their email address or by their reference ID. Use this endpoint before initiating a transfer to ensure the recipient is valid.

The response will include the recipient's user ID if the email or reference ID exists in the system. If the provided information does not exist or does not belong to a valid user, an error will be returned.

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

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/jsonYesFormat of the request body

Query Parameters

NameTypeRequiredDescription
rqtypestringYesType of verification - either 'email' or 'refid'
rqvaluestringYesValue to verify - either email address or reference ID of the recipient

Examples

Verify by Email

Request Example

GET /user_transfer_check_receiver?rqtype=email&rqvalue=recipient@example.com

Body:

{}

Verify by Reference ID

Request Example

GET /user_transfer_check_receiver?rqtype=refid&rqvalue=REF123456

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_check_receiver",
    "STATUS": "OK"
  },
  "DATA": {
    "userid": "usr_67890fghij"
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_check_receiver",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_transfer_check_receiver",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "User with this provided profile not found (MPS384532812704072)"
  }
}

Implementation Notes

  • When using rqtype=email, provide the complete email address of the recipient
  • When using rqtype=refid, provide the reference ID/code of the recipient
  • The returned user ID can be used to initiate a fund transfer using the user_transfer_create endpoint
  • This verification step is recommended before any transfer to avoid errors

Get Wallet Activity

Retrieve the activity log for a user's wallet

GET

Description

This endpoint fetches comprehensive wallet activity data including deposits, transfers, and transaction history. The results are aggregated from multiple sources to provide a complete view of all financial activities associated with the user's wallet.

Each activity record includes the following details:

  • rxtype: Type of record ('deposit', 'transfer', or 'history')
  • marker: Unique identifier for the transaction record
  • userid: User identifier associated with the activity
  • description: Human-readable description of the transaction
  • amount: Amount involved in the transaction
  • pxtype: Transaction type ('credit', 'debit', 'failed', or 'pending')
  • recorded: Timestamp when the transaction was recorded

This information is valuable for providing users with a transaction history, generating financial reports, and tracking wallet usage. The pxtype field ('credit' or 'debit') indicates whether funds were added to or removed from the wallet, while the rxtype field provides context about the source of the transaction.

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

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/jsonYesFormat of the request body

Query Parameters

NameTypeRequiredDescription
pagestringNoPage number for pagination (default: "false")

Request Example

GET /user_wallet_activity?page=1

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_activity",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "rxtype": "deposit",
      "marker": "dpst_12345abcde",
      "userid": "usr_12345abcde",
      "description": "Deposit to wallet",
      "amount": 250,
      "pxtype": "credit",
      "recorded": "1686744645"
    },
    {
      "rxtype": "transfer",
      "marker": "trfr_67890fghij",
      "userid": "usr_12345abcde",
      "description": "Funds Transfer to John Doe",
      "amount": 100,
      "pxtype": "debit",
      "recorded": "1686833450"
    },
    {
      "rxtype": "history",
      "marker": "hist_24680abcde",
      "userid": "usr_12345abcde",
      "description": "Service fee for airtime purchase",
      "amount": 5,
      "pxtype": "debit",
      "recorded": "1686933550"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_activity",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "user_wallet_activity",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "No data matching your query was found (MPS251625232617252)"
  }
}