Developer Guide and Track Changes
Updated: 25-Jan-25 | Previous: 11-Nov-24
May change with prior notice.
Change Logs
| Date | Change |
| 11-Nov-2024 | Initial Documentation |
| 26-Jan-2025 |
|
| 10-Feb-2025 |
|
| 25-March-2025 |
|
Introduction
The set of WebAPI endpoints for MPOS, served by PPA MPOS Server will accept authenticated JSON (JavaScript Object Notation) only. The methods defined in each endpoint return varrying data objects in the format of JSON as a standard REST transport, together with standard W3C HTTP Responses with the standard response codes. E.g. 200, 201, 401, 501.
The requests may originate from, regardless of the platform (mobile, servers, etc.), as long as the request is in JSON format using the HTTPS protocol.
All the requests shoud be authenticated, and authorized.
Subscriber/User Registration
The subscriber who will consume the services of the MPOS should register a WebAPI account to Philippine Ports Authority.
- The subscriber will start by getting a user account based on PPA's single-sign-on mechanism. PPA Support team will provide the initial recording of this account via a form filled-out by the subscriber. The account or user name is email-based, so a company service email is preferable instead of a personal email. The registration info will be emailed to the user once the Account Administrator has processed the registration.
- The subscriber will login to the Account Center server using the email provided at https://stage-account.ppa.com.ph if using the the test or staging server. For live, https://account.ppa.com.ph to change the credentials, and choose whether to authenticate transaction posting via JWT or API Key.
- Once the above has been performed, authentication and authorization of posting transactions can begin.
Authentication and Authorization of Post Requests
There are two ways of authenticating for sending transaction requests. PPA's Account Center and SSO systems cater these two methods.
API Key — Authentication by API Key is used to provide a simple and basic authentication process. With this authentication, large volume of requests are processed continuously without having to get or acquire new tokens. The authentication is done by assigning a unique and secret key for each of the subscriber. These keys are used in each of the request's authentication header, exactly or similar method to using JWT Keys. This type of token never expires, unless changed by the subscriber/user.
JSON Web Tokens — At the time of this writing, JSON Web tokens or JWT is the defacto-standard when it comes to securing online transactions via the world wide web. It is more secured compared to API Keys as JWT tokens are generated uniquely on every new authorization or acquisition (usually 20 mins or less as the standard), or longer if so preferred.
Authenticating and Posting Requests Using API Keys
- Using the email provided as the credential from the subscriber/user, and the key generated inside the Account Center https://stage-account.ppa.com.ph for testing and https://account.ppa.com.ph for live, the posting can begin.
- The request is sent to MPOS Web API Server via the header Bearer, using https request. Please see the Web API Documentation for the usage and posting of transactions.
- The subscriber can continuously post data using the API Key. Again, the key has no expiry, unless replaced or a new key has been generated in the Account Center.
- If the subscriber belongs to multiple systems, each API Key is assigned for each system and can be managed in the Account Center.
- Refer to flowchart below for the business process of the API Key-based authentication.
Persisting the API Key(s)
As a user and subscriber of the system, the key persistent and safekeeping are their responsibilities. It can be kept in a configuration file, database, etc., encrypted by your own utility program, and decrypt whenever it is up for usage.
For heightened security measures, once the key is generated, it can no longer be seen again in the Account Center key management panel. It is stored as a hash data in the server and cannot be deciphered nor decrypted. Once forgotten, a new one should be generated.
API Key Response Error Table
In cases where there are errors during posting, below HTTP codes will be returned from the request, together with REST JSON record containing the details.
| Error Name | Status Code | HTTP Label | Description |
| UnauthorizedAccess | 401 | Unauthorized | The supplied API key does not have the correct permissions to access the API being called. Contact the support team to determine the permissions and accessible content for your key. |
| InvalidApiKey | 401 | Unauthorized | The supplied API key is invalid or already expired, revoked or replaced, and cannot be used for any API request calls. Log in to Account Center to generate another valid key. |
Using Gatekeeper to generate API Keys
The Gatekeeper portal is used to authenticate and authorize the subscribers for different applications. For MPOS, this portal is used to generate the API Key needed to post into PPA's financial system.
Prerequisite The subscriber should already have their valid credentials. Request to the technical support team if you have yet to get your credentials, but you will have to provide your email.
Steps
- Go to stage-account.ppa.com.ph
- Enter your credentials. Note: The system will send a code to your registered email, this will only occur once the token is expired.
- Click the API Key under Settings
- Navigate through the page and click the Generate Key button.
Once you generate the key, make sure to have your own copy. The key will be censored afterwards. In case of lost or forgotten key, you can always generate another one. Once generated, the previous key will become invalid.
Email:
Password:
How to Use Load Testing
The Load Testing tool is for functional users that does not need to rely on using API tools like Postman, Thunder Client, or Bruno. The test mimicks the postFinancialData and postReceiptsToIports endpoints.
Prerequisite The subscriber should already be logged in and have a valid API Key before proceeding.
Steps
- Go to and select the Load Testing item from the navigation bar.https://stage-mpos.ppa.com.ph/
- Populate the API Key field with your valid account API Key.
- Navigate through the page and click the Generate Data button. Once clicked, all the data for Receipt Header and Receipt Lines are populated.
The Generate Data button populates all the field with perfect data, this means that there should not be any error present when the Post Data button is clicked. To mimick erroroneous scenarious, the subscriber can change or remove values from the input fields.
Once the subscriber is ready to submit the trasaction, click the Post Data button to proceed with the data validation and transaction processing.
- Once Populated, the subscirber can opt to change or remove any of the values from the input fields.
The subscriber can add and remove lines but added lines are not pre-populated, meaning that the subscriber needs to input values for it before posting.
