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

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_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

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 wallet history to fetch (transaction, owner, mk, all)
rqvl	string	No	Search value corresponding to the rqtp (marker ID, owner ID, or transaction ID). Default: "false"
page	string	No	Page 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

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
amount	number	Yes	Amount 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

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_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

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
email	string	Yes	Recipient's email address
amount	number	Yes	Amount to transfer
messge	string	No	Optional 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

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_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 email exists before initiating a transfer

GET

Description

This endpoint checks if a user with the specified email address exists and can receive wallet transfers. Use this before initiating a transfer to ensure the recipient is valid.

The response will include the recipient's user ID if the email exists in the system. If the email 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

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
email	string	Yes	Email address of the recipient to verify

Request Example

GET /user_transfer_check_receiver?email=recipient@example.com

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 email not found (MPS384532812704072)"
  }
}