Postman collection for testing the POS-Padi API
\nPOS-Padi is a web-based POS management platform designed to give agents and business owners full control over their operations, from tracking profits and resolving disputes to managing terminals and receiving fraud alerts in real-time.
\nThe platform tackles key problems in the informal POS sector like fraud, delayed dispute resolution, and limited cash access, by offering a smart, centralised system for real-time visibility, financial tools, and customer engagement.
\nThis collection documents both backend services:
\nDjango Backend (Auth & Core User System)
\nHandles authentication (JWT), users, agents, customers, and company records.
\nExpress Backend (Transaction Layer)
\nHandles disputes, transactions, and real-time notifications.
\nBoth services are deployed separately and consume tokens issued after login.
\nAll endpoints are protected and require a JWT token in the Authorization header:
Authorization: Bearer <access_token>\n\nThe Django service generates Tokens upon successful login.
\nCheck the login response for the JWT access token.
\nGrouped folders by service and functionality (e.g., Auth, Customers, Transactions, Disputes)
Live examples and prefilled request bodies
\nTests and pre-request scripts
\nGlobal variables: authToken, djangoUrl, nodeUrl
Environment setup file for dev and production
\nVisual tags for HTTP method, auth requirement, and service
\nJohnathan β Django Developer
\nAnyim Ossi β Django Developer
\nMichael Peter β Express Developer
\nAdeyemi β Express Developer
\nSteve β Django Developer
\nOgaga β Express Developer
\nKayode β Express Developer
\nSanele Skhosana β Django Developer
\nOyinda β Express Developer
\nThis API is part of the POS-Padi MVP project and is intended for internal frontend use, contributor collaboration, and (eventually) public developer testing under controlled environments.
\nAgent/terminal assignment
\nDaily transaction tracking
\nCustomer profile & history
\nExpense tagging & profit breakdown
\nReal-time dispute logging
\nPush alerts for fraud & cash low
\nInteract securely with the POS-Padi backend.
\nLog in via the login user endpoint(Authentication folder) to generate an auth token.
\nToken is automatically added to the collection variables.
\nβLog in is required.
Follow the implementation docs.
\nRegisters a new user on the POS-Padi platform. This endpoint allows a new user(Owner/Aggregator) to register by providing their details. An OTP is sent to their email for verification.
\nMethod: POST
Not required
\n400 Bad Request β Email already in use, missing required fields, or invalid data
\n500 Internal Server Error β Unexpected server failure
\nVerifies a newly registered Aggregator's email using a One-Time Password (OTP) that was sent to their email address during registration. Successful verification activates the user account and allows login.
\nMethod: POST
Not required
\n400 Bad Request β Invalid or expired OTP, or email mismatch
\n404 Not Found β No verification record found for the provided email
\n500 Internal Server Error β Server-side error during OTP validation
\nResends the One-Time Password (OTP) to the email address of a registered but unverified Aggregator. This is useful when the original OTP has expired or was not received.
\nNot required
\n400 Bad Request β Email already verified or not associated with a pending registration
\n404 Not Found β No user found with the provided email
\n429 Too Many Requests β User has exceeded the allowed OTP resend attempts
\n500 Internal Server Error β Unexpected server-side failure
\nAuthenticates a verified user (Aggregator, Agent, or Admin) and returns a refresh and access JWT token used for accessing protected resources. This token must be included in the Authorization header of all subsequent requests.
Not required
\n400 Bad Request β Invalid email or password
\n403 Forbidden β Account not yet verified
\n500 Internal Server Error β Unexpected server issue during login
\nIssues a new JWT access token using a valid refresh token. This allows users to stay authenticated without needing to log in again, ensuring a seamless and secure session renewal experience.
\nNot required β uses a refresh token in the request body.
\n401 Unauthorized β Expired, invalid, or blacklisted refresh token
\n400 Bad Request β Missing or malformed refresh token
\n500 Internal Server Error β Server error during token regeneration
\nLogs out the currently authenticated user by invalidating/ blacklisting their refresh token. This action prevents reuse of the token for future access and is essential for securing user sessions on shared or public devices.
\nβ
Required β The user must be logged in and include a valid Authorization token.
401 Unauthorized β Missing or invalid access token
\n400 Bad Request β Invalid or expired refresh token
\n500 Internal Server Error β Logout failed due to internal error
\nHandles secure access to the platform. This folder includes endpoints for user registration, login, logout, password management, email verification, and user session summary. All authenticated routes require a valid JWT token.
\n","_postman_id":"e9a1117b-9351-410c-9d34-090d6de6a27a","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","name":"POS-Padi API","type":"collection"}}},{"name":"User Password","item":[{"name":"Forgot Password","id":"7863476b-2440-4dfa-a1c2-b2f938703f1f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"email\": \"agent1@test.com\"\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"https://pos-padi-django-backend.onrender.com/api/v1/users/forgot-password/","description":"Initiates the password reset process by sending a One-Time Password (OTP) to the userβs registered email. This endpoint is used when a user has forgotten their password and needs to create a new one.
\nNot required
\n404 Not Found β No account found with the provided email
\n429 Too Many Requests β OTP resend limit exceeded
\n500 Internal Server Error β Server issue during OTP generation or delivery
\nThis endpoint allows an authenticated user to change their password by providing the current password, a new password, and confirming the new password.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","name":"POS-Padi API","type":"collection"}},"urlObject":{"path":["users","change-password",""],"host":["https://pos-padi-django-backend.onrender.com/api/v1"],"query":[],"variable":[]}},"response":[{"id":"0e893ac0-df10-48cc-8656-964c9fa24b11","name":"Password changed successfully.","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicCompletes the password reset process by allowing the user to submit a valid OTP and set a new password. This is used after initiating a \"Forgot Password\" request.
\nNot required
\n400 Bad Request β Invalid OTP, missing fields, or weak password
\n404 Not Found β No active password reset request found for the email
\n500 Internal Server Error β Failed to reset password due to a server issue
\nRetrieves key details of the currently authenticated user, including identity, role, permissions, and company association. This endpoint is typically used to initialize user-specific data for dashboards and role-based access control.
\nβ
Required β The request must include a valid Authorization header with a bearer token.
No request body required
\n401 Unauthorized β Missing or invalid token
\n500 Internal Server Error β Failed to fetch user data
\nProvides endpoints to fetch a summary of the authenticated userβs data, including roles, permissions, and general account metadata. These endpoints are useful for initializing frontend dashboards and personalizing user experiences after login.
\n","_postman_id":"09a050f2-87dc-4b80-a1c5-43b99ab4fe10","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","name":"POS-Padi API","type":"collection"}}},{"name":"User Preferences","item":[{"name":"Toggle email setting","id":"bac76d4c-f6e9-4cb0-8ae5-e4040d36ef90","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[],"url":"https://pos-padi-django-backend.onrender.com/api/v1/users/email-toggle-setting/","description":"This endpoint allows a user to toggle their email setting.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","name":"POS-Padi API","type":"collection"}},"urlObject":{"path":["users","email-toggle-setting",""],"host":["https://pos-padi-django-backend.onrender.com/api/v1"],"query":[],"variable":[]}},"response":[{"id":"a735f2ff-1e04-495c-862a-5fe65a1f6484","name":"Email settings updated successfully.","originalRequest":{"method":"PATCH","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis endpoint allows a user to toggle their push notification settings.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","name":"POS-Padi API","type":"collection"}},"urlObject":{"path":["users","push-notification-setting",""],"host":["https://pos-padi-django-backend.onrender.com/api/v1"],"query":[],"variable":[]}},"response":[{"id":"c652d553-16dd-4bcd-b9f8-3950e84930c0","name":"Push notification settings updated successfully.","originalRequest":{"method":"PATCH","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis endpoint allows a user to update their profile information.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","name":"POS-Padi API","type":"collection"}},"urlObject":{"path":["users","update-profile",""],"host":["https://pos-padi-django-backend.onrender.com/api/v1"],"query":[],"variable":[]}},"response":[{"id":"c3a658c2-ecd9-47d1-b91b-273b793e2691","name":"Profile updated successfully.","originalRequest":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json"},{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicContains endpoints related to user identity, access control, and account lifecycle management. This includes authentication flows (login, registration, password reset), email verification processes, and endpoints for retrieving key user data summaries. These APIs are essential for establishing secure user sessions and personalizing the platform experience.
\n","_postman_id":"833d4c28-b847-4afe-8bf7-0f138eaad31f","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","name":"POS-Padi API","type":"collection"}}},{"name":"Companies","item":[{"name":"Create New Company","id":"62aec5eb-1f57-4d17-bc12-cd6c23d0e1eb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"name\": \"Creates a new company record on the POS-Padi platform. Companies represent business entities under which agents and terminals operate. Only users with the owner or admin role are authorized to perform this action.
β Required β Must include a valid JWT token
\nOwner: Can register and manage their own company.
\nAdmin: Can create and manage companies across the platform.
\nAgent: β Not permitted to access this endpoint.
\nFetches a list of companies on the POS-Padi platform. This endpoint supports pagination, sorting, and keyword-based search. Only admin and owner Roles can access this endpoint. Agents are not permitted.
β Required β Must include a valid JWT token
\nOwner: Can retrieve only their own company details.
\nAdmin: Can retrieve any or all company records in the system.
\nAgent: β Access is restricted.
\n\n\n
Example usage:https://pos-padi-django-backend.onrender.com/api/v1/companies/?search=mighty&ordering=name&page=2
403 Forbidden β User lacks permission
\n400 Bad Request β Invalid query parameter
\n500 Internal Server Error β Data retrieval failed
\nA search term.
\n","type":"text/plain"},"key":"search","value":"Which field to use when ordering the results.
\n","type":"text/plain"},"key":"ordering","value":"A page number within the paginated result set.
\n","type":"text/plain"},"key":"page","value":"Returns summary performance metrics for a company, such as transaction volume, revenue, and activity distribution. This endpoint is typically used to power dashboards and business insights. Only users with the owner or admin role can access this data.
β Required β Must include a valid JWT token
\nOwner: Can retrieve metrics for their own company and filter by individual agents.
\nAdmin: Can retrieve metrics for any company across the platform.
\nAgent: β Not permitted to access metrics.
\n\n\n
Example usage:https://pos-padi-django-backend.onrender.com/api/v1/companies/metrics/?start_date=2024-01-01&end_date=2024-03-01&agent_id=agt_93b84
403 Forbidden β User lacks permission
\n400 Bad Request β Invalid date format or query structure
\n500 Internal Server Error β Error occurred while calculating metrics
\nStart date for filtering metrics (YYYY-MM-DD).
\n","type":"text/plain"},"key":"start_date","value":"End date for filtering metrics (YYYY-MM-DD).
\n","type":"text/plain"},"key":"end_date","value":"Agent ID for filtering metrics.
\n","type":"text/plain"},"key":"agent_id","value":"Updates the details of an existing company on the POS-Padi platform. This endpoint is used to modify company-level information such as name, location, or administrative identifiers. Only users with the owner or admin role are authorized to make updates.
β Required β Must include a valid JWT token
\nOwner: Can update their own company's details.
\nAdmin: Can update any company in the system.
\nAgent: β Not permitted to use this endpoint.
\n\n\nβ οΈ At least one field must be provided to trigger an update.
\n
403 Forbidden β User lacks permission (agent role or not the company owner)
\n404 Not Found β Company Name not found or not linked to user
\n400 Bad Request β No valid fields provided or validation failed
\n500 Internal Server Error β Error occurred while saving changes
\n(Required) A unique value identifying this company.
\n","type":"text/plain"},"type":"any","value":"Deactivate a company from the POS-Padi platform using its unique ID. This action is irreversible and should be used with caution. Only users with the admin role are authorized to perform this operation.
β Required β Must include a valid JWT token
\nAdmin: Can delete any company in the system.
\nOwner: β Not permitted to delete companies.
\nAgent: β Not permitted to access this endpoint.
\n\n\n
Example: https://pos-padi-django-backend.onrender.com/api/v1/companies/123e4567-e89b-12d3-a456-426614174000/
403 Forbidden β User does not have permission to delete companies
\n404 Not Found β Company with the given ID does not exist
\n500 Internal Server Error β Failed to process deletion request
\n(Required) A unique value identifying this company.
\n","type":"text/plain"},"type":"any","value":"Provides endpoints for managing business entities and their associated POS terminals. Only Owners and Admins are authorised to perform these actions, such as creating companies, registering terminals, assigning agents, and monitoring activity. These APIs support centralised business management and real-time oversight of terminal operations.
\n","_postman_id":"d2b83891-5e53-4aae-945e-95018745aaf7","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","id":"7ed69a69-89aa-4bdd-9996-5f3eb5634f52","name":"POS-Padi API","type":"collection"}}},{"name":"Agents","item":[{"name":"Create New Agent","id":"b35907a8-fbf8-4788-af02-5bf109c7e897","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"first_name\": \"Agent\",\n \"last_name\": \"Agent\",\n \"email\": \"agent1@test.com\",\n \"phone\": \"+234000000000\"\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"https://pos-padi-django-backend.onrender.com/api/v1/agents/","description":"Registers a new Agent under the authenticated user's company. This endpoint is used by Owners or Admins to onboard field agents and assign them to one or more terminals for transaction handling.
\nβ Required β Must include a valid JWT token
\nOwner: Can create agents within their own company.
\nAdmin: Can create agents under any company.
\nAgent: β Not authorized to perform this action.
\n\n\n<p >Additional metadata like address, gender, or NIN can be included depending on system configuration.</p>
\n
403 Forbidden β User lacks permission (e.g., agent role)
\n400 Bad Request β Missing fields or email already exists
\n500 Internal Server Error β Unexpected error while creating the agent
\nFinalizes the agent onboarding process by allowing the agent to set a password. This is typically used after an agent account is pre-created by an owner or admin, and the agent is given a link or instruction to complete registration.
\nNot required β this is a public setup step typically performed once.
\n\n\n<p >This request is generally tied to a tokenized URL or context to associate the agent with their pending profile.</p>
\n
400 Bad Request β Passwords do not match or are too weak
\n410 Gone β Onboarding token/session has expired
\n404 Not Found β No pending agent account found for onboarding
\n500 Internal Server Error β Unexpected failure during account activation
\nAuthenticates an onboarded Agent and returns a JWT token used for accessing protected resources. Returns access and refresh tokens. This token must be included in the Authorization header of all subsequent requests.
Not required
\n400 Bad Request β Invalid email or password
\n403 Forbidden β Account not yet verified
\n500 Internal Server Error β Unexpected server issue during login
\nUpdates the status of an agent.
Each request inverts the status of the specified agent; Active/Inactive
A unique value identifying this agent.
\n","type":"text/plain"},"type":"any","value":"Retrieves a paginated list of agents associated with the authenticated userβs company. Supports basic search and ordering functionality. Only owner and admin roles can access this endpoint.
β Required β Must include a valid JWT token
\nOwner: Retrieves agents linked to their own company.
\nAdmin: Retrieves all agents across the platform.
\nAgent: β Not authorized to access this endpoint.
\n\n\n
Example: https://pos-padi-django-backend.onrender.com/api/v1/agents/?search=Grace&page=2&ordering=first_name
403 Forbidden β Insufficient permission (agent role)
\n400 Bad Request β Invalid query parameters
\n500 Internal Server Error β Failed to retrieve agent data
\nA search term.
\n","type":"text/plain"},"key":"search","value":"Which field to use when ordering the results.
\n","type":"text/plain"},"key":"ordering","value":"A page number within the paginated result set.
\n","type":"text/plain"},"key":"page","value":"Fetches the details of a specific agent using their unique ID. This endpoint is used to display agent profiles, status, or assignments. Only accessible to users with the owner or admin role.
β Required β Must include a valid JWT token
\n