POS as a Platform Documentation
- Olorunferanmi Joel
Analytics
Table of Contents
3.1 API Keys
3.1.1 API Key Lifecycle
Introduction
This documentation provides the essential resources for integrating with Moniepoint POS terminals, including authentication methods, API references, webhook subscription management, and change management guidelines.
Getting Started Guide
Quick Setup Instructions
Sign Up/Login: To get started, sign up for an account on the business console.
Generate API Key:
Business owners create API keys with specified permissions and assigned business
During key generation, define the scope and specify the business the key applies to.
API key will be generated once make sure it is saved and secured.
Authentication:
Use the Bearer Authentication method to pass the API key in the Authorization header of the HTTP request.
API requests with an invalid or expired key will return a
401 Unauthorizedor403 Forbiddenerror.
Test Your API Key: Use the Key Introspection API to check the status of your API key, its associated scope, and whether it has expired.
Authentication Overview
API Keys
API keys are the primary authentication method for connecting with the POS platform. The business owner generates each key, which grants access to specific resources based on predefined scope and permissions.
API Key Lifecycle:
Creation: Business owners create API keys with specified permissions and scope.
Expiration: The key will expire after the configured duration.
Scope: defines the actions and resources the API key can interact with.
Modifications: Keys are not modifiable. If scope or permissions change, a new key must be created.
How to Use the API Key
Include the API key in the Authorization header as a Bearer token in your HTTP requests:
Authorization: Bearer <API_KEY>
Valid Key: If the key is valid, the server processes the request.
Invalid Key: The server will respond with
401 Unauthorized.Invalid Scope: If the API key does not have the appropriate scope, the server will return a
403 Forbiddenerror.
API Reference
Key Introspection API
To view details about an API key (scope, linked businesses, validity), you can call the Key Introspection endpoint:
Base_URL: https://posapi.development.moniepoint.com
Endpoint: GET /v1/introspect
Request Example
To inspect an API key, use the following curl command:
curl -X 'GET' \ '{Base_URL}/v1/introspect' \ -H 'accept: application/json' \ -H 'Authorization: Bearer my_access_token'Replace
my_access_tokenwith your actual API key in theAuthorizationheader.
Success Response (200 OK)
If the API key is valid, the response will look like this:
{
"scopes": [
"webhook:write",
"webhook:read",
"webhook:delete"
],
"businesses": [
{
"id": 150,
"businessName": "your busineess name"
}
],
"authMethod": "API_KEY"
}scopes: Lists the actions the API key has permission to perform (e.g.,webhook: write,webhook: read,webhook: delete).businesses: Lists the businesses the API key is associated with, including the business ID and name.authMethod: The method of authentication used (e.g.,API_KEY).
Error Response (401 Unauthorized/403 Expired Key)
If the API key is invalid or expired, you will receive a 401 Unauthorized error with the following response:
{ "error": "Unauthorized", "message": "Invalid key provided." }error: The error type (e.g.,Unauthorized).message: A description of the issue (e.g., "Invalid key provided.").
Webhook
Subscription Management
Developers can subscribe to various transaction events (purchases, withdrawals, transfers, bill payments, etc.) and receive real-time notifications when these events occur. Webhooks facilitate communication with the merchant’s server to update external systems (e.g., ERP software, and customer notifications).
API Endpoints Subscription Management
Create Subscription
Endpoint: POST /v1/webhook-subscriptions
Create a new webhook subscription for the specified transaction events.
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
Request Body:
Success Response (200 OK):
Error Response (400 Bad Request):
Get All Subscriptions
Endpoint: GET /v1/webhook-subscriptions?page=${}&size=${}
Retrieve all webhook subscriptions associated with the API key.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
page | The page number for pagination (starting from 0). | 0 | Specifies the page number to fetch (useful for handling large datasets) |
size | The number of items to display per page. | 20 | Specifies the number of events to display per page (in this case, 20 events per page). |
sort | The sorting order of the events. | asc | Specifies the sorting order, either |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
Get Subscription by ID
Endpoint: GET /v1/webhook-subscriptions/{subscriptionId}
Retrieve a specific webhook subscription by its ID.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in. |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
Update Subscription by ID
Endpoint: PUT /v1/webhook-subscriptions/{subscriptionId}
Update an existing webhook subscription by its ID.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in. |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Available Event Types
Event Type | Description |
|---|---|
V1_POS_WITHDRAWAL_TRANSACTION | Event triggered for a POS withdrawal transaction. |
V1_POS_PURCHASE_TRANSACTION | Event for purchase transactions made via POS. |
V1_POS_CARD_TRANSFER_TRANSACTION | Event for transferring funds using a card at POS. |
V1_POS_BILL_PAYMENT_TRANSACTION | Event for bill payments made through POS. |
V1_POS_TRANSFER_TRANSACTION | Event for pos transfers initiated from POS. |
V1_TRANSFER_TRANSACTION | General transfer transaction event. |
V1_POS_COLLECTION_TRANSACTION | Event-triggered when a merchant monnify collection is made through POS |
V1_POS_PAY_CODE_TRANSACTION | Event for transactions using a merchant monnify pay code at POS. |
V1_POS_AIRTIME_TRANSACTION | Event for airtime purchase transactions through POS |
V1_POS_BOOM_TRANSACTION | Event-related to Boom-specific transactions via POS. |
Body:
Success Response (200 OK):
Error Response (404 Not Found):
Delete
Subscription by ID
Endpoint: DELETE /v1/webhook-subscriptions/{subscriptionId}
Delete a webhook subscription by its ID.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in. |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
{ "message": "Webhook subscription deleted successfully" }
Managing Webhook Subscription Authentication and Secrets
Get Subscription Authentication Details
Endpoint: GET /v1/webhook-subscriptions/{subscriptionId}/authentication
Retrieve the authentication details for a specific webhook subscription.
Query Parameters Explanation:
subscriptionId:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in. |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
Error Response (400 Bad Request):
Update Subscription Authentication
Endpoint: PUT /v1/webhook-subscriptions/{id}/authentication
Update the authentication details for a webhook subscription.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in. |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Request Body:
Success Response (200 OK):
Error Response (400 Bad Request):
Regenerate Secret for Subscription
Endpoint: POST /v1/webhook-subscriptions/{subscriptionId}/secret
Regenerate a new secret for the given webhook subscription ID.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in. |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
Error Response (400 Bad Request):
Fetch Secret for Subscription
Endpoint: GET /v1/webhook-subscriptions/{subscriptionId}/secret
Fetch the current secret for the given webhook subscription ID.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in. |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
Error Response (404 Not Found):
Managing Webhook Subscription Events and Logs
Get Webhook Subscription Event by ID
Endpoint: GET /v1/webhook-subscription-events/{subscriptionEventId}
Retrieve a specific webhook subscription event by its ID.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in. |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
Error Response (404 Not Found):
Get All Webhook Subscriptions
Endpoint: GET /v1/webhook-subscription-events
This endpoint retrieves webhook subscription events based on specified filters and pagination parameters.
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
subscriptionId | Unique identifier for the webhook subscription whose events you're interested in. | 1ebb99a3-89a2-4074-81ea-553564845f8a | Filters the events based on the given subscription ID. |
from | The start date (in YYYY-MM-DD format) to filter events that occurred from this date. | 2025-02-05 | Filters the events from this start date. |
to | The end date (in YYYY-MM-DD format) to filter events that occurred up to this date. | 2025-02-06 | Filters the events up to this end date. |
eventType | The type of event to filter by. | V1_POS_TRANSACTION, V1_POS_WITHDRAWAL_TRANSACTION, V1_POS_PURCHASE_TRANSACTION, V1_POS_CARD_TRANSFER_TRANSACTION, V1_POS_BILL_PAYMENT_TRANSACTION, V1_POS_TRANSFER_TRANSACTION, V1_TRANSFER_TRANSACTION, V1_POS_COLLECTION_TRANSACTION, V1_POS_PAY_CODE_TRANSACTION, V1_POS_AIRTIME_TRANSACTION, V1_POS_BOOM_TRANSACTION, V1_POS_DATA_PURCHASE | Filters the events to include only the specific type of event (V1_POS_TRANSACTION in this case). |
status | The status of the events to filter by. | SUCCESS, PENDING, FAILED | Filters the events to include only those that have a |
page | The page number for pagination (starting from 0). | 0 | Specifies the page number to fetch (useful for handling large datasets) |
size | The number of items to display per page. | 20 | Specifies the number of events to display per page (in this case, 20 events per page). |
sort | The sorting order of the events. | asc | Specifies the sorting order, either |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
Error Response (404 Not Found):
Get Webhook Subscription by ID
Endpoint: GET /v1/webhook-subscriptions-events/{subscriptionEventId}
Retrieve a specific webhook subscription by its ID.
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
| Unique identifier for the webhook subscription whose events you're interested in |
| Filters the events based on the given subscription ID. |
Success Response (200 OK):
Error Response (404 Not Found):
Force Resend event based on filters
Endpoint: POST /v1/webhook-subscriptions-events/resend
sending the event back to the User
Query Parameters Explanation:
Query Parameter | Description | Example Value | Purpose |
|---|---|---|---|
subscriptionId | Unique identifier for the webhook subscription whose events you're interested in. | 1ebb99a3-89a2-4074-81ea-553564845f8a | Filters the events based on the given subscription ID. |
from | The start date (in YYYY-MM-DD format) to filter events that occurred from this date. | 2025-02-05 | Filters the events from this start date. |
to | The end date (in YYYY-MM-DD format) to filter events that occurred up to this date. | 2025-02-06 | Filters the events up to this end date. |
eventType | The type of event to filter by. | V1_POS_TRANSACTION, V1_POS_WITHDRAWAL_TRANSACTION, V1_POS_PURCHASE_TRANSACTION, V1_POS_CARD_TRANSFER_TRANSACTION, V1_POS_BILL_PAYMENT_TRANSACTION, V1_POS_TRANSFER_TRANSACTION, V1_TRANSFER_TRANSACTION, V1_POS_COLLECTION_TRANSACTION, V1_POS_PAY_CODE_TRANSACTION, V1_POS_AIRTIME_TRANSACTION, V1_POS_BOOM_TRANSACTION, V1_POS_DATA_PURCHASE | Filters the events to include only the specific type of event (V1_POS_TRANSACTION in this case). |
status | The status of the events to filter by. | SUCCESS, PENDING, FAILED | Filters the events to include only those that have a |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
Success Response (200 OK):
Error Response (404 Not Found):
Get Webhook Subscription Event logs by Event Id
Endpoint: DELETE /v1/webhook-subscriptions-events/{subscriptionEventId}/logs
get webhook subscription event logs by event ID.
Query Parameters Explanation:
subscriptionEventId:Description: Unique identifier for the webhook subscription whose events you're interested in.
Example Value:
1ebb99a3-89a2-4074-81ea-553564845f8aPurpose: Filters the events based on the given subscription ID.
Field | Description | Example Value | Purpose |
|---|---|---|---|
| Unique identifier for the webhook subscription whose events you're interested in |
| Filters the events based on the given subscription ID. |
Headers
Field | Description | Example Value | Purpose |
|---|---|---|---|
Authorization | The API key is used for authentication. | mptd_1a6b6f719d864bb7a88b3fd3bf77513c_3e06ba | Authenticates the request by verifying the provided API key. The key is sent as a Bearer token in the Authorization header. |
POS_BUSINESS_ID | The unique identifier of the business using the POS system. | 150 | Specifies which business the request is for, ensuring that the API knows which business context the request is operating under. |
| Unique identifier for the webhook subscription whose events you're interested in |
| Filters the events based on the given subscription ID. |
Success Response (200 OK):
Error Response (404 Not Found):
Testing and Validation Procedures
Before integrating the webhooks and API functionality, ensure to test your configurations in the sandbox environment. You can verify that your system responds correctly to the event notifications and check that your API calls are working as expected.
Test API Calls: Ensure all required headers (including the API key) are included in the request.
Test Webhook URL: Verify that the URL you provide for webhook subscriptions is correctly receiving the events and processing them.