Lucidy API

v1.02

Table of Contents

I. Purpose

II. Scope

III. Policies

IV. Quick Start

V. Setting up API Account

1. API Information
2. Authentication
3. Security Mode
4. IP Whitelisting
5. Transaction Callback URL
6. Disabled Switch
7. "Save Settings" button
8. "Delete this Account" button

VI. API Commands

1. bal command
2. load command
3. status command

VII. Webhook

VIII. Testing

IX. Security and best practices

X. Troubleshooting

I. Purpose

1. This serves as documentation for the Application Program Interface (API) between the users and the ^DOMAINDESC^ system.
2. The API allows the users of ^DOMAINDESC^ system a direct connection to its facilities for faster and more reliable services.

II. Scope

This document covers the following:

1. Querying of account balance
2. Processing of product request
3. Querying of product request status

III. Policies

1. Acceptable Use

   1. Purpose: Use the API only for its intended purpose.
   2. Prohibited Actions: Do not use the API for any illegal activities, spamming, or to harm ^DOMAINDESC^ system.

2. Data Privacy

   1. User Data: Ensure that any data collected from API responses is stored securely and in compliance with all applicable data protection laws.
   2. Anonymity: Do not attempt to re-identify anonymized data provided by the API.

3. Security

   1. Secure Connections:
      • HTTPS Requirement: All API request must be made over HTTPS to ensure data security.
      • Encryption: Ensure all data transmitted is encrypted.
   2. Reporting Vulnerabilities:

      If you discover any security vulnerabilities, please report them immediately to ^DOMAINDESC^ admin.

4. Distribution of this document

   This document is strictly confidential and is covered by NDA. Distribution of this document in any form will require written permission from ^DOMAINDESC^.

IV. Quick Start

1. Setup/Configuration

   The following configuration is the quickest way to start using the API services:

   • Create an API account via the API Account Management.
   • Edit your API Account
   • Set API Version to Lucidy
   • Set Authentication Mode to Standard UN/PW Pair
   • Assign User Name and Password. You can also use the Generate button () to automatically generate a secure password.
   • Set Security Mode to Plain Authentication
   • Set Disabled to OFF
   • Save the settings

   This is not the most secure setup. Please read the remaining of the API document (particularly Chapter V - Setting up) to know more how to secure your connection.

2. API Requests

   At this point, you can start performing API request. There are three API commands available:

   • bal - to get the account balance
   • load - to perform product request
   • status - to perform status query of the product request
   1. bal command

      To perform account balance inquiry, you can use the following codes:

      Loading, please wait...

      Edit the above code and replace the User Name and Password with the one from API Account Management

      PRO TIP: You can copy and paste the codes into the browser's console. First, copy the code and paste into notepad. Replace the username and password with the one from your API account. If you are using Chrome, press F12 to open the console. Paste the codes and it will execute the command. You can also use the built-in test feature under API Account Management.

      Upon execution, the API system will return JSON format response:

      Loading, please wait...

      If there are no errors, you will receive a result similar to the above. The fields are described as follows:

      • ab - available balance
      • cb - current balance
      • curr - currency
      • rescode - Result Code
      • resmsg - Result Message

      If there are errors, the rescode will be a non-zero number and the ab, cb, and curr fields will be absent from the result. Refer to rescode list for the complete list.

   2. load command

      To perform load request, you can use the following codes:

      Loading, please wait...

      Just like in the bal command, replace User Name and Password with the one from API Account Management.

      There are three (3) additional fields required by load command, these are :

      • pcode - Product Code
      • dst - Destination
      • ctxid - Client Transactions ID

      For the pcode field, you can use TSTS5 as product. Normally, the test product TSTS5 will be made available for you, if not, please contact ^DOMAINDESC^ admin. For this test product, it does not matter what you put in dst field, but it needs to have a value or it will return an error or a non-zero rescode.

      Finally, edit the ctxid with your own tracking ID and make sure your ctxid is unique for each load request or it will return an error. Only characters a-z, A-Z, 0-9, underscore (_), dash (-), and period (.) is allowed, any other characters will be filtered out. The ^DOMAINDESC^ system checks for duplicate ctxid for the last 2 hours. If you use the same ctxid within the last 2 hours, it will return a 131 rescode or "duplicate request error".

      Upon execution, the API system will return JSON format response:

      Loading, please wait...

      If there are no errors, you will receive a result similar to the above. The fields are described as follows:

      • rescode - Result Code
      • resmsg - Result Message
      • status - Status of request
      • tid - Transaction ID

      The status field will normally return QUEUED and the tid is the assigned Transaction ID for this request. Take note of the tid field, this is required when performing the next step, which is the status command.

      If there are errors, the rescode will be a non-zero number and the status and tid fields will not be present from the response. Refer to rescode list for the complete list.

   3. status command

      To perform status query, you can use the following codes:

      Loading, please wait...

      Just like in the bal command, replace User Name and Password with the one from API Account Management.

      An additional field is required by status command:

      • tid - Transaction ID

      The tid field, comes from your previous load command as server response.

      Please note that you can only use the status command on transactions made within one hour. Any transactions made more than an hour ago will result in rescode 137 or "Value for field 'tid' is invalid." If you need to check statuses of older transactions, use the Products Sales.

      Upon execution, the API system will return JSON format response:

      Loading, please wait...

      If there are no errors, you will receive a result similar to the above. The fields are described as follows:

      • rescode - Result Code
      • resmsg - Result Message
      • respmsg - Response Message numeric ID
      • respmsg_code - Response Message code
      • respmsg_detail - Response Message detail
      • status_id - Status ID of request
      • status_detail - Status of request in detail

      The result can be grouped into three (3) parts:

      • res group - composing of rescode and resmsg representing the result of the API request
      • respmsg group - composing of respmsg, respmsg_code, and respmsg_detail representing the "Response Message" of the load request
      • status group - composing of status_id and status_detail representing the status of the load request.
      Each part of the group is just different data format of the response. I.e. respmsg is the numeric format of respmsg_code, and respmsg_detail is the wordy or long version of the respmsg.

      The complete list of Response Messages and Statuses can be viewed from their respective dedicated pages.

      If there are errors in the API request, the rescode will be a non-zero number and only rescode and resmsgfields are available. Refer to rescode list for the complete list.

      Please take extra attention to the following detail in the next paragraph.

      As mentioned earlier, the res group (i.e. rescode and resmsg) are the result of API request. A rescode of 0 means there were no errors in the API request. The status group are the status of the load request. For example, below is an example of a successful API command (hence, rescode=0), but the load request failed (status_id=-1), with the respmsg_code being "TELCO_DECLINED".

      Loading, please wait...

      It is also possible to receive the following status command result when you invoke the status command too early after issuing the load command.

      Loading, please wait...

      This means the load request is still being processed. Typically, a load request is fulfilled after 15 to 20 seconds. The best practice is to use the Transaction Callback. If you want to use the status command, wait 15 seconds after the load command and poll every 15 to 20 seconds after.

      load command -> wait 15 to 20 seconds -> status command -> poll every 15 to 20 seconds.

V. Setting-up API Account

1. API Information

   The first step is to create an API account, this is done by going through API Account Management and clicking the
   Create API Account button
   at the lower part of the page. You will then be presented with a form asking for Name and Detail. The Name and Detail fields does not hold any importance when performing API transactions. The Name field will be used on tables and pulldown list and the Detail field can be used as personal notes for the API account. Click the "add" button at the button of the form to complete this process.

   Next is to edit your API account to configure some settings and preferences. To edit, click the edit button at the left side of the table entry. It will go to a page with more setting options for your API account.

   The first information you will see is the apicode. Upon creating an API Account, the system will generate a unique code designated as apicode. Depending on your selected Authentication Mode, you may or may not need to use the apicode.

2. Authentication

   This API comes in three (3) authentication modes. Depending on the selected mode, the required parameter changes. Below are the list of Authentications Modes with detailed description and required fields to send to the API system.

   1. Standard UN/PW Pair

      This is the most basic authentication mode, and is also the most unsecure method. The authentication only requires username and password. You can type your desired username and password at the designated fields. You can also use the generate button () to automatically generate a secure password.

      During API request call, the username and password will be sent directly as parameters.

      Field Name	Field Value
      username	User Name
      passwd	Password

   2. SHA256 UN/PW Pair

      This authentication mode is more secure than the Standard UN/PW Pair, but the procedure is also more complex. Similar with the Standard UN/PW Pair, you can type your desired username and password at the designated fields. You can also use the generate button () to automatically generate a secure password.

      During API request call, you will need to send apicode and auth fields instead of username and password.

      Field Name	Field Value
      apicode	API Code
      auth	SHA256( User Name + SHA256(Password) )

      As mentioned under V.1 API Information, the apicode is generated and the first item when you edit your API Account.

      The auth field is generated by first performing SHA256 on the password, then concatenate username and the SHA256 password. Finally, perform SHA256 on the concatenated string. The apicode and final SHA256 data designated as auth will be sent as parameters to the API webhook.

   3. Token

      Token-based authentication is similar to SHA256 UN/PW Pair but instead of the client providing the username and password fields, the API system will generate the token utilizing the full 32-characters making it harder to guess. Token-based authentication is as secure (or even more secure depending on how complex the username and password) than the SHA256 UN/PW Pair and less complicated to setup.

      During API request call, you will need to send apicode and token fields instead of username and password.

      Field Name	Field Value
      apicode	API Code
      token	Token

   Remember to save your password and token. ^DOMAINDESC^ does not save your passwords and tokens in clear text. They are hashed using SHA256 before being sent to the servers for storage. This means you cannot retrieve your passwords and tokens from this page or anywhere else. If you forget your passwords or tokens, you will need to regenerate them.

3. Security Mode

   This API comes in two (2) security modes.

   1. Plain Authentication

      This mode relies only on your selected authentication mode. As soon as the API client sends the load command, the API system will immediately process the request.

   2. Callback Authentication

      Callback Authentication is similar to Two-Factor Authentication or 2FA. The purpose of this Security Mode is to confirm the request made by remote server to ensure that the request is valid, authorized, and intentional.
      

      The API System will connect to the clients' system to confirm the request made by the client. This only works with load command. Upon sending a load command, the API system will send the following information to the Security Callback URL:

      Field Name	Field Value
      ctxid	Client Transaction ID

      For Lucidy API, it is expected that the client's system will validate the ctxid sent to the Security Callback URL. The client's system must respond with "ctxid approved". Any response will result a non-zero rescode.

      When this mode is selected, Security Callback URL field will appear and is required. This is the client's system that will validate the request.

4. IP Whitelisting

   This is the list of IP Addresses that will be allowed to perform API request for this API account. Ensure you only type one IP per line or it will cause problem blocking all your request. Just leave this field blank if you do not want to use IP Whitelisting.

   Do not rely on IP Whitelisting as security measure, there are ways to spoof the IP Address. Best practice is to use strong Authentication Mode such as SHA256 UN/PW Pair or Token-based and use Security Callback.

5. Transaction Callback URL

   This is where the API system will send the status of your previously initiated transaction through the load command.

   The Transaction Callback URL is optional, if you do not provide the URL, you can still get the status of your load command by polling the API System using the status command. However, polling can waste the resources of both the API System and the Client's System. The use of Transaction Callback is highly recommended for smoother operation and using only the status command after five (5) minutes has passed without receiving status update through the Transaction Callback URL.

   The API System will send the following fields:

   Key	Value
   tid	Transaction ID assigned by the API
   ctxid	Client Transaction ID assigned by client (your Transaction ID)
   status	Status of request in numeric format. Click here for the complete list.
   status_detail	Translation of 'status' field.
   respmsg	Response Message in numeric format Click here for the complete list.
   respmsg_code	Short code translation of 'respmsg' field.
   respmsg_detail	Longer translation of 'respmsg' field.

   The complete list of Response Messages and Statuses can be viewed from their respective dedicated pages.

6. Disabled Switch

   The Disabled switch is for disabling the API Account in case needed by the API client to disable their access temporarily or permanently. When the account is first created, the API account is defaulted to disabled.

   • - Means the account is NOT disabled, or ENABLED and will be allowed to perform transactions.
   • - Means the account is disabled, or is NOT allowed to perform transactions.

   Do not forget to set Disabled to OFF before you perform or send API commands.

7. "Save Settings" button

   Save Settings

   This button will save any changes you made to the API Account. Be sure to save your changes before using the Test features of the API Account editor.

8. "Delete this Account" button

   Delete this Account

   Use this button to delete the API account. It is best to delete or disable account that you will not use to minimize any potential security risk.

VI. API Commands

There are three (3) API commands available, bal, load, and status.

1. bal command

   The bal command will return the available and current balances of your account.

   To initiate a bal command, you only need to include the following fields to your authentication fields.

   Field Name	Field Value
   state	pao_api
   cmd	bal

   The API System will then reply with a JSON formatted string with fields defined as follows:

   The system will return JSON string with the following fields:

   Key	Value
   rescode	rescode list
   resmsg	Detailed info about the rescode
   ab	Available Balance of the account.
   cb	Current Balance of the account.
   curr	Currency of the balances

   Available Balance is the amount at your disposal when performing load transactions. If the product value is greater than your Available Balance, your load transaction request will fail with an insufficient fund error message.

   Current Balance is the amount that does not include any pending transactions.

   To understand the difference between the two, let us assume a scenario. You have a balance of 1,000 and you wanted a product that cost 100.
   ab: 1000
   cb: 1000
   product cost: 100

   When you initiate a load transaction request, the API system will normally reply with QUEUED. At this point, if you perform balance request, you should have the following result:
   ab: 900
   cb: 1000
   

   It means, only 900 is available for your next load transaction, but since the load transaction request is not yet complete, you may have 1,000 balance depending on the outcome of the first load transaction. Eventually, the load transaction request will be complete and there can be two outcome:
   If the transaction is SUCCESSFUL:
   ab: 900
   cb: 900
   If the transaction FAILED:
   ab: 1000
   cb: 1000
   

2. load command

   The load command is used when you want to request a product or to initiate a load transaction request.

   To initiate a load command, you need to include the following fields to your authentication fields:

   Field Name	Field Value
   state	pao_api
   cmd	load
   pcode	List of Products
   dst	Destination of Load (i.e. Mobile number, Account number, or Subscriber Number)
   amt	Amount if product allows incremental value
   ctxid	Client Transaction ID

   The pcode or "Product Code" is the product being requested. To view the list of products available to your API Account, go to the API Account Management and click the button at the left side of the account and check the "Tagged Products". To view details about the product, go to Products Listing. You can also request ^DOMAINDESC^ admin for the list.

   The dst is the destination of the product being requested. This can be mobile number, account number, or subscriber number depending on the requirement of the product.

   The amt is the amount parameter required by incremental products or products that allows arbitrary amount instead of fixed amount. Provide the amt parameter if the product requires it.

   The ctxid is the Transaction ID of the client's backend system. This is for client's own tracking of transaction on the client-side system. Only characters a-z, A-Z, 0-9, underscore (_), dash (-), and period (.) is allowed, any other characters will be filtered out. The ^DOMAINDESC^ system checks for duplicate ctxid for the last 2 hours. If you use the same ctxid within the last 2 hours, it will throw a 131 error or duplicate request error.

   The API system will return JSON string with the following fields:

   Key	Value
   rescode	rescode list
   resmsg	Detailed info about the rescode
   tid	Transaction ID
   status	Status of request

   Transaction ID ortid is the ^DOMAINDESC^'s side transaction ID in contrast with ctxid which is the client side or your own side of transaction ID. You will use Transaction ID or tid when searching for the transaction on ^DOMAINDESC^'s system side like when asking for support or checking the Products Sales list.

   Finally, the status key returns the status of the load request. This will normally return QUEUED, meaning the request is queued for processing, otherwise, it will return FAILED for any errors. The complete list of statuses can be viewed here

3. status command

   The status command is used to get the status of the load transaction request or load command.

   To initiate a status command, you need to include the following field to your authentication fields.

   Field Name	Field Value
   state	pao_api
   cmd	status
   tid	Transaction ID

   tid is the Transaction ID returned by the load command operation.

   Note that status command will only return status of transactions made in the last hour to save resources and keep the API System optimized and responsive. If your tid came from transaction made more than one hour ago, it will return rescode of 137 or 'Value for field tid is invalid.' If you need to check statuses of older transactions, use the Products Sales.

   ---

   The API system will return JSON string with the following fields:

   Key	Value
   rescode	rescode list
   status	Status of request in numeric format. Click here for the complete list.
   status_detail	Translation of 'status' field.
   respmsg	Response Message in numeric format Click here for the complete list.
   respmsg_code	Short code translation of 'respmsg' field.
   respmsg_detail	Longer translation of 'respmsg' field.

To easily understand the returned values, we can reorder the returned keys as follows:

• rescode - Result Code
• resmsg - Result Message
• respmsg - Response Message numeric ID
• respmsg_code - Response Message code
• respmsg_detail - Response Message detail
• status_id - Status ID of request
• status_detail - Status of request in detail

And then group them as follows:

• res group - composed of rescode and resmsg
• respmsg group - composed of respmsg, respmsg_code, and respmsg_detail
• status group - composed of status_id and status_detail

The res group (i.e. rescode and resmsg) are the result of API request. A rescode of 0 means there were no errors in the API request. The status group are the status of the load request. For example, below is an example of a successful API command (hence, rescode=0), but the load request failed (status_id=-1), with the respmsg_code being "TELCO_DECLINED".

Loading, please wait...

It is also possible to receive the following status command result when you invoke the status command too early after issuing the load command.

Loading, please wait...

This means the load request is still being processed. Typically, a load request is fulfilled after 15 to 20 seconds. The best practice is to use the Transaction Callback. If you want to use the status command, wait 15 seconds after the load command and poll every 5 to 10 seconds after.

load command -> wait 15 to 20 seconds -> status command -> poll every 5 to 10 seconds.

VII. Webhook

Lucidy API uses HTTP-based webhook. All API transactional request are performed via the webhook. Lucidy API accepts both POST and GET methods, but POST is strongly recommended.

The webhook URL is as follows:

^rooturl^shin/lite.p

Here are example codes from commonly used programming languages to demonstrate how the webhook URL is being used:

1. Using curl

   Loading, please wait...

2. Using Lynx

   Loading, please wait...

3. Using php

   Loading, please wait...

4. Using javascript

   Loading, please wait...

5. Using kotlin

   Loading, please wait...

For more examples of different programming languages, please contact ^DOMAINDESC^ admin.

VIII. Testing

Loading, please wait...

Loading, please wait...

Loading, please wait...

IX. Security and best practices

X. Troubleshooting