First, take note of your API Code. Depending on the next step, you might need this.
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.
For the API version, the first version, Lucidy, is normally selected unless a different API is advised by the admin.
View the complete API Documentation for details.
This is the most basic authentication mode, and is also the most unsecure method. API client will send username and passwd as parameters to the API web hook.
This authentication mode is much secure than the Standard UN/PW Pair, but the procedure is also complex. API client will first perform SHA256 on the password, then concatenate username and the SHA256 password. Finally, perform SHA256 on the concatenated string. The APICODE and final SHA256 data will be sent as parameters to the API web hook.
API client will send API Code and Token as parameters to the API web hook. Token-based authentication is as secure as the SHA256 UN/PW Pair and less complicated. Token is also generated by the system and utilizing the full 32-characters making it harder to guess.
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.
This mode requires a Security Callback URL. 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 |
The Security Callback URL should confirm if they sent ctxid and reply with ctxid approved if the request is approved. Any other message will cause the load command to fail with rescode 302 or Security Callback failed.
Based on the selected Authentication Mode and Security Mode, the following is your security assessment:
Higher bar in green means very secure, while low bar in red means the selected combination of authentication and security is not ideal.
The webhook URL is as follows:
^srooturl^shin/lite.p
All API request will use this URL.
To perform an API request, a POST is sent to the URL above, along with additional fields depending on the request, plus the authentication fields based on selected authentication mode.
For BALANCE request, the following fields are needed:
For LOAD request, the following fields are needed:
For STATUS request, the following fields are needed:
You can try out your API Account configuration using this form. In order to test load and status commands, additional information are required such as the Client Transaction ID or ctxid. Please fill-in additional information on the fields below:
This is the product code loaded to the destination number. If the product supports incremental load, use this field to set the amount This is the destination number where the product will be sent or loaded. This is the client's backend Transaction ID. This is the Transaction ID returned by the system during load command. This is required by the status command.Below is the sample code for performing request:
Make sure you have saved any changes first before testing the codes or it will base the test from the original configuration.
| Field Name | Field Value |
|---|---|
| state | pao_api |
| cmd | bal |
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 |
| Field Name | Field Value |
|---|---|
| state | pao_api |
| cmd | load |
| pcode | List of Products* |
| dst | Destination of Load (i.e. Mobile number) |
| amt | Amount if product is incremental |
| ctxid | Client Transaction ID** |
*Please check with your Account Manager for the list of available products.
**This is the Transaction ID of the client's backend 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 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 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 side like when asking for support or checking the Products Sales list.
**This is 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.
| Field Name | Field Value |
|---|---|
| state | pao_api |
| cmd | status |
| tid | Transaction ID* |
*This is the Transaction ID returned by the 'load' cmd operation.
The 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. |
| Field Name | Field Value |
|---|
| username | User Name |
| passwd | Password |
| apicode | API Code |
| auth | SHA256( User Name + SHA256(Password) ) |
| apicode | API Code |
| token | Token |
var request = $j.ajax({
type: "POST",
url: "^rooturl^shin/lite.p",
data: {
^params^
}
});
request.done(function( msg ) {
alert( "Server returned : " + msg );
});
request.fail(function( jqXHR, textStatus ) {
alert( "Request failed: " + textStatus );
});