STAR TELECOM Co.

LTD (UNITEL)
Nongbone Rd, Phonexay Village, Saysettha District
Vientiane Capital, Lao P.D.R

TECHNICAL DOCUMENTATION FOR

PARTNER
REVISION HISTORY

DATE VERSION DESCRIPTION AUTHOR

17-Jun-2020 1.0.0 Create New Mr. Duong Van Minh
15-Jul-2020 1.0.1 Update Error Code Mr. Duong Van Minh

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

1
 Table of Contents
TECHNICAL DOCUMENTS............................................................................ 1
PARTNER CONNECTION MODEL ............................................................... 3
BANK - EWALLET ............................................................................................ 4
TOKEN API: .................................................................................................. 5
CHECK EWALLET ACCOUNT: ............................................................... 6
TRANSFER MONEY: .................................................................................. 7
EWALLET – BANK ........................................................................................... 9
ACCOUNTING ................................................................................................. 10
Master Account for a representative wallet of Bank ................................ 10
Steps of accounting for transfer from EWALLET to BANK .................. 10
Steps of accounting for transfer from BANK to EWALLET .................. 11
LIST OF ERROR CODES ............................................................................... 12

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

2
PARTNER CONNECTION MODEL

USSD *999#

Core 1 Core 2

Core 3 Core 4

DB 1 DB 2
Mobile
App

Core 1 Core 2
DB

API
IP PORT

External Zone Internal Zone

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

3
BANK - EWALLET
Transfer Bank – Ewallet

Customer BANK u-money

Money transfer function:

Bank to u-money eWallet Save the processing log into DB

Check Customer account information

Send transaction request to
Input the Phone Number on u-money wallet system
u-money wallet
(Account exists or doesn't exist)

Error message:
Error message:
Failure (Not
Failure (Not authenticated, <<Fail>>
authenticated, Account
Account does not exist, Account
does not exist, Account
canceled, ...)
canceled, ...)

<<Success>>

Display information returned from

Customers enter the amount
u-money: Returns information query results:
to be transferred and click
Account, Status, Customer Name, Account, Status, Customer Name, ...
button Transfer
...

Perform transaction processing from

Submit request for money
BANK and return transaction results
transfer to u-money system
(Success, failure, Timeout, ...)

<<Fail>>

<<Success>>

Processing
transaction results

Display notification of Save the processing log into DB

Returns transaction
transaction results for
results. Show notification.
customers
(Success, failure, ...)
(Success, Failure)
Phase 1

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

4
GENERAL DESCRIPTION:
• Framework: spring security
• Authentication request: Oauth2
• Format generate token: JWT
TOKEN API:
- When a partner needs to generate new token or token expired, have to call API to
generate a new token.
- Request template:
URL template http://183.182.100.174:8083/ewallet/token (Public test IP)
Production is private IP and need open connection on firewall.
Method POST
Headers Content-Type: application/x-www-form-urlencoded
Authorization Basic Auth
(clientID pair, the clientSecret is provided by the Wallet)
Body
username <username>
password <password>
grant_type password

Authorization Username: bank-st-clientid

Password: bank-st-clients3cr3t
Body Username: bank-st
Password: bank-st-pw
grant_type: password

• Response template: SUCCESSFUL:

{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MjI
wOTU5OTAsInVzZXJfbmFtZSI6ImJhbmstc3QiLCJhdXRob3JpdGllcyI6WyJST0xFX01FUl9S
RVFfT1RQIiwiUk9MRV9NRVJfR0VUX0FDQ19JTkZPIiwiUk9MRV9CQU5LIl0sImp0aSI6IjZiM
2M3NjFhLWM4YmQtNDcwOS04NTBhLWM3ZjYxMmVjZGY1ZSIsImNsaWVudF9pZCI6ImJhbmstc3
QtY2xpZW50aWQiLCJzY29wZSI6WyJyZWFkIiwid3JpdGUiXX0.3jLOeFI-
t4oPyT9GVpVlX2asHh88MUo51Us68a9FOts",
"token_type": "bearer",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbW
UiOiJiYW5rLXN0Iiwic2NvcGUiOlsicmVhZCIsIndyaXRlIl0sImF0aSI6IjZiM2M3NjFhLWM
4YmQtNDcwOS04NTBhLWM3ZjYxMmVjZGY1ZSIsImV4cCI6MTYyNDY4MzY5NiwiYXV0aG9yaXRp
ZXMiOlsiUk9MRV9NRVJfUkVRX09UUCIsIlJPTEVfTUVSX0dFVF9BQ0NfSU5GTyIsIlJPTEVfQ
kFOSyJdLCJqdGkiOiI3MDA1MjRjMC00OWI4LTQ2NTItODlmOS1iZGJhNGY5YTVjZjYiLCJjbG
llbnRfaWQiOiJiYW5rLXN0LWNsaWVudGlkIn0._owablZvcQuevPhXfrk5qFVNr-
AOv0S62XOj9geHV5Y",
"expires_in": 419,
"scope": "read write",
"jti": "6b3c761a-c8bd-4709-850a-c7f612ecdf5e"
}

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

5
 Parameter definition

NAME TYPE DESCRIPTION LENGTH

access_token STRING Authenticated token to send request 500
token_type STRING Type of token 50
refresh_token STRING Token refresh 500
expires_in NUMBER Time to expired 100
scope STRING Scope of token 100
jti STRING jti 36

CHECK EWALLET ACCOUNT INFO:

• Security:
o Whitelisting IP (Partner provide the IP to whitelist)
o Restrict by login user role
- Request template:
http://183.182.100.174:8083/api/v1.0/account/getInfo (Public test
URL template IP)
Production is private IP and need open connection on firewall.
Method POST

Headers Content-Type application/json

Authorization bearer <provided-token-after-authentication>

{
"phoneNumber":"8562095873197",
Body "serviceCode":"BANKCODE_TRANSFER"
}
• Response template:
SUCCESSFUL:
{
"responseCode": "00000",
"message": "Successful",
"timestamp": "2021-05-27T13:12:33.023+0700",
"transId": null,
"transDate": "20210527131232",
"accountName": "Mr Bobby ແກ້ ວດວງດ
ີ ",
"accountStatus": "ACTIVE",
"tier": "1",
"minAmount": 0.0,
"maxAmount": null
}

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

6
 Parameter definition

NAME TYPE DESCRIPTION LENGTH

The phone number to receive money
phoneNumber STRING 15
at the ewallet system
Service checking Account Info. The
serviceCode STRING 15
code of partner
responseCode NUMBER Response code 500
message STRING Meassage of response 50
timestamp STRING Time of transaction 100
transId NUMBER Transaction ID 500
transDate STRING Date of transaction 100
accountName STRING Customer Name 100
accountStatus STRING Status of Account 10
minAmount NUMBER Minimum Amount to transfer 36
maxAmount NUMBER Maximum Amount to transfer 36

TRANSFER MONEY:
• Security:
o Whitelisting IP (Partner provide the IP to whitelist)
o Restrict by login user role
- Request template:
http://183.182.100.174:8083/api/v1.0/bank/transferMoney (Public
URL template test IP)
Production is private IP and need open connection on firewall.
Method POST

Headers Content-Type application/json

Authorization bearer <provided-token-after-authentication>

{
"phoneNumber": "8562095873197",
"bankAccount": "3832028446464443459",
"amount": "10001",
Body "bankTransId": "FT19130LN36W1",
"content": "Bopby 交易成功 ການເຮ ັ ດທ
ຸ ລະກ
ໍ າ"
}

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

7
 • Response template:
SUCCESSFUL:
{
"responseCode": "00000",
"message": "Successful",
"timestamp": "2020-04-21T10:39:24.384+0700",
"transId": "200421000121335",
"transDate": "20200421103924"
}

Parameter definition

NAME TYPE DESCRIPTION LENGTH

The phone number to receive money
phoneNumber STRING 15
at the ewallet system
bankAccount STRING Bank account to transfer 25
amount NUMBER The amount of transaction 36
bankTransId STRING Transaction ID on bank 100
content STRING Content of transaction 100
responseCode NUMBER Response code 50
message STRING Message of response 100
timestamp STRING Time of transaction 100
transId STRING Transsaction ID from u-money system 100
transDate STRING Date of transaction 100

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

8
EWALLET – BANK
Transfer Ewallet – Bank

Customer u-money wallet BANK

Money transfer function:

u-money eWallet to Bank Save the processing log into DB

Choose Bank code to transfer

money (LVB, JDB, MJDB, )

Send request to check Check Customer account information

Enter the Bank Account to
account information to BANK on BANK system
transfer money
system (Account exists or doesn't exist)

Error message: Error message:

Failure (Account does not Failure (Account does not <<Fail>>
exist, Account canceled, ...) exist, Account canceled, ...)

<<Success>>

Customers enter the amount Display information returned from u- Returns information query results:
to be transferred and click money: Account, Status, Customer Name,
button Transfer Account, Status, Customer Name,... ...

Perform transaction processing from

Send request for money transfer to
BANK and return transaction results
BANK system
(Success, failure, Timeout, ...)

<<Fail>>

<<Success>>

Processing
transaction results

Display notification of Save the processing log into DB

transaction results for Returns transaction
customers results. Show notification.
(Success, Failure) (Success, failure, ...)
Phase 1

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

9
ACCOUNTING
Master Account for a representative wallet of Bank
MASTER
W_BANK_(NAME_OF_BANK)
ACCOUNT
TEMPORARY
W_BANK_(NAME_OF_BANK)_TEMP
ACCOUNT
FEE
W_BANK_(NAME_OF_BANK)_FEE
ACCOUNT

Steps of accounting for transfer from EWALLET to BANK

Customer Account (-) Amount
Customer Account (-) Fee
STEP 1
W_BANK_(NAME_OF_BANK)_TEMP (+) Amount
W_BANK_(NAME_OF_BANK)_TEMP (+) Fee
W_BANK_(NAME_OF_BANK)_TEMP (-) Amount
W_BANK_(NAME_OF_BANK)_TEMP (-) Fee
STEP 2
W_BANK_(NAME_OF_BANK) (+) Amount
W_BANK_(NAME_OF_BANK)_FEE (+) Fee
RESPONSE RESPONSE
RESULT ACCOUNTING
CODE DESCRIPTION

W_BANK_(NAME_OF_BANK)_TEMP
(-) Amount
Accounting for
W_BANK_(NAME_OF_BANK)_TEMP transferring money
Success 1 (-) Fee from temporary
wallet to bank's
W_BANK_(NAME_OF_BANK) (+) master wallet
Amount
W_BANK_(NAME_OF_BANK)_FEE
(+) Fee

W_BANK_(NAME_OF_BANK)_TEMP
(-) Amount Accounting for
transferring money
Fail -1 W_BANK_(NAME_OF_BANK)_TEMP from temporary
(-) Fee wallets to customer
wallets
Customer Account (+) Amount
Customer Account (+) Fee
Keep Customer's
Timeout -5 Cross check with BANK money in temporary
wallets

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

10
Steps of accounting for transfer from BANK to EWALLET

Customer Account (-) Amount

Customer Account (-) Fee
STEP 1
W_BANK_(NAME_OF_BANK) (+) Amount
W_BANK_(NAME_OF_BANK) (+) Fee

RESPONSE RESPONSE
RESULT ACCOUNTING
CODE DESCRIPTION
Customer Account (-) Amount
Customer Account (-) Fee Accounting for
W_BANK_(NAME_OF_BANK) (+) transferring money
Success 1 Amount from customer’s wallet
to bank's master
W_BANK_(NAME_OF_BANK)_FEE wallets
(+) Fee
W_BANK_(NAME_OF_BANK) (-)
Amount Accounting for
transferring money
Fail -1 W_BANK_(NAME_OF_BANK)_FEE from bank’s master
(-) Fee wallets to customer
Customer Account (+) Amount wallets
Customer Account (+) Fee
Keep Customer's
Timeout -5 Cross check with BANK money in Bank’s
master wallets

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

11
LIST OF ERROR CODES
DETAIL
ERROR TYPE
ID ERROR DESCRIPTION
CODE
1 00000 Success Transaction is successful

2 99999 Fail ERROR - Unknown Error

3 99998 Fail ERROR - Token is invalid

4 10130 Fail ERROR - Input/Param is invalid

5 10532 Fail ERROR - Transaction Timed out

6 10112 Fail ERROR - Transaction is invalid

7 10111 Fail ERROR – Account invalid

10113
10114
10115
8 10116 Fail ERROR - Account is invalid
10117
10118
10122
9 10119 Fail ERROR - No data found
10000
10001
10002
10003
10 Fail ERROR - OTP
10004
10005
10006
10007
10817
10819 ERROR – Core – Wallet account not
11 Fail
10811 authorized
10810
ERROR – Core – Account balance exceeds
12 10831 Fail
allowed limit
ERROR – Core – Account balance is less than
13 10832 Fail
allowed
ERROR – Core – The maximum amount of
14 10834 Fail
transactions exceeds the allowed limit

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

12
 DETAIL
ERROR TYPE
ID ERROR DESCRIPTION
CODE
ERROR – Core – The minimum amount of the
15 10833 Fail
transaction is less than the allowed limit
10835 ERROR – Core – The amount of debit in the
16 Fail
10846 day exceeded the allowed limit
10836 ERROR – Core – The amount of credit in the
17 Fail
10845 day exceeded the allowed limit
ERROR – Core – The balance of the bank
18 10839 Fail master wallet is not sufficient to make the
transaction
10197 ERROR – Core – The receiving account is
19 Fail
10198 blocked
10851
10861
10811
20 Fail ERROR – Core – Transaction not configured
10862
10863
10864
10844
10841
10840
10870
10871 ERROR – Core – Transaction rule not
21 Fail
10872 configured
10873
10874
10875
10876
ERROR – Core – Account is not standardized
22 10180 Fail
(Non KYC Customer)
10933
23 Fail ERROR – Core – Bank Code Not Found
10934
10130
10912
24 10105 Fail ERROR - Others
10106
99990

© 2020 Developed by Management Software Center - IT Star Fintech

Copyright Star Fintech SOLE Co., LTD

13