Welcome to Philippine Ports Authority
Web API RESTful Services
EOR API Endpoint Documentation
Press Ctrl-F5 to load the latest version of this document.
Updated: 14-Mar-2024 | Previous: 19-Feb-2024
May change with prior notice.
Go to Change Logs
# Method Endpoint Address Updated | Previous
1 POST
/api/signin/LoginGetJwtAsync
14-Mar-2024
2 POST
/api/eor/PostDataForAckReceipt
07-Feb-2024
3 POST
/api/eor/RequestJwtEncryption
12-Mar-2024
Request and Response Handling UPDATED
Duplicate or Conflicting Data 31-JAN-2024 T3:00PM
JWT Token Expiry and request error response payloads 31-JAN-2024 T3:00PM
Handling Response Payloads 31-JAN-2024 T3:00PM
Response Payloads, ErrorName and HTTP Status Codes 09-FEB-2024 T8:00PM
Method Endpoint Address / Description Updated
POST
(live) https://api.ppa.com.ph/api/signin/LoginGetJwtAsync
(staging) https://webapi-staging.ppa.com.ph/api/signin/LoginGetJwtAsync
Authorize Web API registered user. This API must be called or accomplished or performed before any or other EOR endpoints can be used by the subscriber.

Both staging and live tokens, cookie and JWT validities are 24 hours and 20 minutes respectively. You DO NOT NEED to authorize or login everytime you make a EOR post request. Once your request is denied or authorization/token has expired, issue another LoginGetJwtAsync request in order to be granted for posting again.

Tip: As a common practice, most systems monitor their acquisition of new tokens in background threads/jobs. Some usually do this every 15 minutes, or 5 minutes before the actual token expires. This is to give seemless experience to the user/automated systems without having to relogin everytime the token expires.

You must persist the JWT token and send it as a Bearer using the header Authorization for every EOR receipt post request.

The cookie-based token is used for the web application pages only. The JWT token is used for web, other subscribing application types such as Windows, Android, iOS, etc.

NOTE: We will no longer support the cookie-based token in the future, especially with the new upcoming version of PPA Web API. Please use the JWT token instead for posting against EOR system.

Request Parameters:
Name Description Type Required
Email The email of the registered user. This is also the user name. string Yes
Password The password to be used by the OPCE subscriber. string Yes
JSON Response:
NOTE: The properties NotBefore and ExpiredAt are both UTC time.
Authentication Response
14-Mar-2024
POST
(live) https://api.ppa.com.ph/api/eor/PostDataForAckReceipt
(staging) https://webapi-staging.ppa.com.ph/api/eor/PostDataForAckReceipt
Request Payload
Name Description Type Required
HASH_CODE The signature of the request payload hashed in 64-length hexadecimal format. Used for validating the original value of the payload. See Hash Utility Method for producing this value. string (64) Yes
TERMINAL_CODE The terminal code of the issuing party. Default is MICT. string (20) Yes
EAR_NUMBER The CHO Electronic Acknowledgement Receipt Number. This is also the unique data coming from the CHO system. string (35) Yes
EAR_DATE The CHO Electronic Acknowledgement Receipt Date. This does not include future dates. Date Yes
CHO_INV_NO The Consolidated Arrastre and Wharfage Invoice referring to the bill from the CHO System. string (20) No
ENTRY_NO The OLRS Number from Value Added Service Provider (VASP). string (40) No
CHO_DEBTOR_CODE The CHO defined Customer Code. string (20) Yes
CUSTOMER_TIN The BIR Registered TIN. Sample format (111-111-111 or 111-111-111-0000 or 111-111-111-00000). string (20) Yes
CUSTOMER_NAME The BIR registered name. This should not contain any special characters. string (100) Yes
BUSINESS_STYLE The BIR Registered Business Style. All the business styles are received directly from BIR. string (100) Yes
CUSTOMER_ADDRESS The BIR registered address. This should not contain any special characters. string (200) Yes
BROKER_NAME The Broker Name that is controlled by the CHO system. string (80) No
HS_CODE The BOC Harmonious Code. string (35) No
VAT_CODE The Value Added Tax Code. string (10) No
EWT_CODE The Expanded Withholding Tax Code. The value is required once EWT column is greater than 0. string (5) No
CWT_CODE The Creditable Withholding Tax Code. The value is required once CWT column is greater than 0. string (5) No
TOTAL_AMOUNT The CHO Receipt Total Amount to pay. This must be derived from the Receipt Lines + VAT less Witholding Tax/es. decimal (12, 3) Yes
VAT The CHO Receipt Value Added Tax Amount. Also pertains to the total VAT amount from the receipt lines. decimal (10, 3) No
CWT The CHO Receipt Creditable Withholding Tax. decimal (10, 3) No
EWT The CHO Receipt Expanded Withholding Tax. decimal (10, 3) No
ReceiptLinesDto[] List|Collection|Enumerable
SERVICE_CODE The CHO assigned Service Code, same as the PPA Coding/ Arrastre. string (10) Yes
SERVICE_DESCRIPTION The CHO Service Description. string (50) Yes
QTY The Line Quantity. decimal (10, 3) Yes
RATE The Service Code Rate. decimal (7, 3) No
PRIMARY_AMOUNT The Primary Amount. decimal (12, 3) Yes
VAT_AMOUNT The Value Added Tax Amount per item. decimal (10, 3) No
EWT_AMOUNT The Expanded Withholding Tax Amount per item. decimal (10, 3) No
CWT_AMOUNT The CHO Receipt Creditable Withholding Tax per item decimal (10, 3) No
Example JSON Request
JSON Payload
Example JSON Response:
The endpoint will emit the JSON record below. Validations are also emitted back for each column or property.
As of February 9, 2024, the Status Code will yield 201/Created when the request is successful, instead of 202/Accepted.
JSON Payload Response
Where:
  • ReceiptIDSN - The ID/Serial Number of the receipt.
    NOTE: This property is sent as the UUID, meaning that it should be strictly 36 in length.
  • ReceiptPrintUrl - The URL that needs to be called (inside a new window) to print the receipt from PPA Web API EOR. e.g.: When a button in ACTS system is clicked for printing.
    There are two url parameters in the URL. They are not case-sensitive:
    • eorIdSn — The value of this parameter is the ReceiptIDSN, and is already provided in the response payload.
    • ejwt — Stands for Encrypted JASON Web Token. This value must be provided if the receipt is to be protected against unauthorized receipt printing. Otherwise, the receipt will be printed without any protection and the public audience will be able to scan the QR Code and print it at will. The value of this parameter is generated by the endpoint /api/eor/RequestJwtEncryption. Leave the value of ReceiptPrintUrl as-is, if public printing is currently allowed by the PPA Web API EOR system.
  • RequestStats - {}
    • EOR_RECEIVE_TIME - The time when the EOR/EPS system has received the request.
    • EOR_VERSION - System Version of EOR that generated the request.
    • EOR_VAL_TIME - The time spent validating all the request payload properties.
    • EOR_PROC_TIME - Time spent for EOR/EPS to record and process data.
    • FIR_PROC_TIME - Time spent for interconnected APPS (PPA Financial) to record and process data.
    • EOR_LEAVE_TIME - Date stamp when EOR/EPS sent the request back to the API client subscriber.
Duplicate or Conflicting Data
In case of the same or exact receipt data has been submitted (hash coded by the PPA Web API Server), below JSON response payload will be emitted back to the subscribing application. The api method will return a http response code of 409 (Conflict), along with its error name.
duplicate post
JWT Token Expiry and request error response payloads
The JWT token will expire in 20 mins on both live and stagnig server. You will need to re-authorize or login again to get a new JWT token. You can handle the re-authorization using the response payloads below.
  • SecurityTokenExpiredException — This happens when the JWT token has expired.
    SecurityTokenExpiredException
  • SecurityTokenInvalidSignatureException — This happens when the JWT token has been tampered or modified.
    SecurityTokenInvalidSignatureException
  • SecurityTokenSignatureKeyNotFoundException — This happens when the JWT token has been slightly tampered or modified.
    SecurityTokenSignatureKeyNotFoundException
Any of the above exceptions will require you to re-authorize or login again to get a new JWT token.
Other exceptions that may occur:
  • SecurityTokenMalformedException - when a supplied token is not of type JWT.
  • SecurityTokenInvalidAudienceException - when a user is not assigned the correct role.
Handling Response Payloads
It is recommended to check either the HTTP response code or the ErrorName of the response payload, or both. The developers of EOR recommend the usage of the ErrorName property when dealing with error responses, as these are originally emitted by the underlying libraries that PPA Web API use.
≡ Back to Index
Response Payloads, ErrorName and HTTP Status Codes
EOR/EPS as a Web API Resful service, follows the Standard HTTP Status Codes, regardless of the request, http or transactions, since the set of Standard HTTP Status Codes HTTP Status Codes are well known and well-understood by the developers. The response payload will contain the following properties in JSON format:
  • StatusCode (number) - The primary indicator of the response status.
  • ErrorName (string) - The secondary indicator of the response status.
  • Message (string) - A text representing information, warning or error.
  • Succeeded (bool) - Indicates whether the request has succeeded or not.
  • ResponseData (JSON) - Content of this property is dynamic, based on the request made. Please check on a successful post request.
  • ResponseError (JSON) - Also, a dynamic JSON object, an array of objects containing the following when validating field/properties:
    • FieldName - The property name of the request object, also the column name in the database.
    • SuppliedValue - The value supplied in the corresponding column.
    • Remarks - The error message of the corresponding column.
    It may also contain the following array of objects when the request is successful but with duplicate records:
    • StatusCode - A standard HTTP StatusCode, example: 409/Conflict
    • Message - Example: An existing, exact receipt data has already been submitted. The original data has been provided in the ResponseData property.
    • Example of the ResponseError property:
      "ResponseError": [ {
      "Code": 409, "Message": "An existing, exact receipt data has already been submitted. The original data has been provided in the ResponseData property."
      } ]
List of ErrorName and HTTP Status Codes
When requesting for posting the receipt, the response payload will contain the following ErrorName and Status:
ErrorName StatusCode Browser Header Text Description
DataValidationError 400 Bad Request

The supplied value is not valid. e.g. the length of the supplied value is incorrect; not in the correct format; data type is wrong; decimal floating point number is outbound than required. etc.

The Remarks field will show the correct formatting.

InvalidDateFormat 400 Bad Request The format of the date is not correct. The Remarks field will show the correct formatting.
PayloadMissing 400 Bad Request Request JSON body of the receipt is missing.
NoContent 204 NoContent A certain record is not found in the EOR/EPS system. Example: A Receipt IDSN is supplied in the print dialog page, but that Receipt IDSN does not exist in PPA's record.
TokenNotFound 403 Forbidden The request being made does not contain JWT token in the Authorization header.
ExistingOrConflictingData 409 Conflict The information (e.g. receipt payload) has already been submitted previously, and is a duplicate request.
SecurityTokenExpiredException 401 Unauthorized The JWT token has expired.
SecurityTokenInvalidSignatureException 401 Unauthorized The JWT token has been tampered or modified.
SecurityTokenSignatureKeyNotFoundException 401 Unauthorized The JWT token has been slightly tampered or modified.
SecurityTokenMalformedException 401 Unauthorized The supplied token is not of type JWT.
SecurityTokenInvalidAudienceException 401 Unauthorized The user is not assigned the correct role.
Below are the HTTP/Response Status Codes when the Financial Bridge Process system has encountered an error.
FinancialBridgeProcessConflict 409 Conflict This happens when a requirement for a certain data is not met. e.g. The tariff and/or service code is invalid, receipt back-dating, etc.
FinancialBridgeProcessError 500 Internal Server/Process Error This happens when an unknown error is not handled in the Financial Bridge Process system, however has been naturally thrown by the Oracle RDMS engine.
FinancialBridgeNoDataFound 204 No Content If the EOR/EPS has not properly recorded the staging data, the Financial Bridge Process system will not be able to process the request.
≡ Back to Index
 07-Feb-2024
POST
(live) https://api.ppa.com.ph/api/eor/RequestJwtEncryption
(staging) https://webapi-staging.ppa.com.ph/api/eor/RequestJwtEncryption
Request Payload
None

IMPORTANT: When calling the endpoint, the JWT token should be sent as a Bearer in the Authorization header of the request.

When printing a receipt from a subscribed system, e.g. ICTSI's ACTS, it opens or redirects to a new browser window. This new window is not covered by the JWT token currently held by the subscriber. Unless, that customer has a user account / access in PPA EOR System. As of the moment, customers do not have this account status yet.

This endpoint encrypts the currently held JWT token of a subscriber. The use of this endpoint is to encrypt the jwt to ejwt (encrypted JWT) as a url parameter when jumping from one web application system to another, as a URL parameter e.g. ICTSI ACTS redirecting or opening a window, to the print a customer's receipt. The ejwt is then decrypted by the EOR/EPS system and only this system can decrypt it. In addition to, this token expires every 20 minutes and its usage is no longer possible even if they are cached by the browser or ISPs.

The endpoint /api/eor/PostDataForAckReceipt JSON response payload, and the property ReceiptPrintUrl will now contain the value below:

"ReceiptPrintUrl" : "https://api.ppa.com.ph/eor/printauth/?eorIdSn=the-guid-eoridsn&ejwt="

Example Response Payload
{
"Message": "JWT encryption request successful.",
"ResponseData": {
"EJwt": "HQTPDtTH91Z%2faX34kkuuiCEOEiNVSj0OjsB5Xvsh9NQaucCmSJpwAQWC7KD3GA4MUeTg0bd3Ju8qJOMdNAOcfpGrwy........"
},
"ResponseError": null,
"ErrorName": null,
"StatusCode": 200,
"Succeeded": true
}
When redirecting or opening a new window to the print window/page of the EOR/EPS system, the URL should contain the ejwt parameter.
https://api.ppa.com.ph/eor/printauth/?eorIdSn=the-guid-eoridsn&ejwt=HQTPDtTH91Z%2faX34kkuuiCEOEiNVSj0OjsB5Xvsh9NQaucCmSJpwAQWC7KD3GA4MUeTg0bd3Ju8qJOMdNAOcfpGrwy........
NOTE: the value of the property EJwt is url-encoded, and shorten for brevity in this documentation. The actual value is longer.
≡ Back to Index
 12-Mar-2024