MOVITEL USSD PUSH API SPECIFICATION

MOVITEL USSD PUSH API SPECIFICATION

1
 MOVITEL USSD PUSH API SPECIFICATION

DOCUMENT HISTORY

Version Date Author In description

1.1 20/03/2021 IT eMola First Draft
Add reqeustId to
1.2 20/04/2021 IT eMola
response
Add refNo param to
1.3 31/05/2021 IT eMola
request
1.4 15/03/2022 IT eMola Add callback function

2
 MOVITEL USSD PUSH API SPECIFICATION

Note:
- We offer SOAP api with an address formatted as below and detail ip, port will be
sent once having a contract signed.
https://xxx.xxx.xxx.xxx:yyyy/BCCSGateway/BCCSGateway?wsdl
- For this document: M means mandatory and O means option.

A. Common Format
1. Request
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://webservice.bccsgw.viettel.com/">
<soapenv:Header/>
<soapenv:Body>
<web:gwOperation>
<Input>
<username>xxx</username>
<password>xxx</password>
<wscode>? </wscode>
<!--Zero or more repetitions:-->
<param name="?" value="?"/>
<rawData>?</rawData>
</Input>
</web:gwOperation>
</soapenv:Body>
</soapenv:Envelope>

- Describe Input:
Tag Name Type Length Description Require
An encrypted string and assigned
username String 1~50 M
for each partner.
An encrypted string and assigned
password String 1~50 M
for each partner.
A keyword to determine which
wscode String 1~30 function will be M
called.
List input values, the name and
param String Undefined value’s belong to each M
function required.

3
 MOVITEL USSD PUSH API SPECIFICATION

An other way to enter input by

rawData String Undefined describe exactly each M
tag for each input.

2. Response
<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:gwOperationResponse
xmlns:ns2="http://webservice.bccsgw.viettel.com/">
<Result>
<error>0</error>
<description>success</description>
<return>Return</return>
<original>Original</original>
<gwtransid></gwtransid>

</Result>
</ns2:gwOperationResponse>
</S:Body>
</S:Envelope>

- Describe Output:
Tag Name Type Length Description Require
A response
error String 1~50 code (view M
table below).
Detail
description String 1~50 description for M
response code.
Response
return,
String Undefined output incase M
original
error = 0

4
 MOVITEL USSD PUSH API SPECIFICATION

- List response code:

ERROR_CODE DESCRIPTION
0 Success when calling detail api
2007 Time out when calling detail api.
1000 Username is invalid
2000 Webservice code is invalid
4000 The request's message's format is not accurate
1001 Username does not exist
Because our system is overloading, please wait another time to
6000
send requests
The connection to DB has some problems. The gateway cannot
7000
handle the request at this time
6001 You don't have the right to access the web service
Your right about calling the web service is expired, please contact
6002
the administrator
Login failed. Please check username, password and your IP
6003
Address and contact the administrator
6004 Login fail due to invalid username.
7001 Database error
2005 Webservice error
6005 Error when load response to DOM
8000 The IP is incorrect
9001 Exception
9002 Error when prepare soap input
3000 Client was not found in database or inactive
2001 Webservice does not found in database or inactive
4001 Requested web service does not exist
5000 Too many requests. Please wait until your other request finish
1002 Username is inactive, please contact the administrator
The web service you requested is inactive, please contact the
2002
administrator
The connection to the web service has problems. Please contact
2003
the administrator
2004 Could not connect to the business web service

5
 MOVITEL USSD PUSH API SPECIFICATION

B.Detail API
1. PushMessage
This api to push a message to customer via USSD
+By default, the system will process synchronously, the system will wait for the
customer to confirm the transaction within 60s, if it exceeds 60s, the system will return an
error code that “The customer did not enter PIN”.
+Optional:
If asynchronous processing is configured, the system will receive the request and
notify the partner when the request has been processed. See point 4.Callback function

The flow chart will be like this:

1.1. Soap Request:

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://webservice.bccsgw.viettel.com/">
<soapenv:Header/>
<soapenv:Body>
<web:gwOperation>
<Input>
<username>xxxxx</username>
<password>yyyyy</password>
<wscode>pushUssdMessage</wscode>
<param name="partnerCode" value=""/>
<param name="msisdn" value=""/>
<param name="smsContent" value="Message will be
display(without amount):"/>
<param name="transAmount" value=""/>
<param name="transId" value=""/>
<param name="language" value=""/>
<param name="refNo" value=""/>
<param name="key" value=""/>
<rawData>?</rawData>
</Input>

6
 MOVITEL USSD PUSH API SPECIFICATION

</web:gwOperation>
</soapenv:Body>
</soapenv:Envelope>

- Description:
Requir
Param Type Length Description
e
msisdn of subscriber
want to push the
msisdn String 9 M
message
prefix: 86/87
Unique value for each
transId String 15-30 M
transaction
The money needs to
transAmount String 1-5 M
payment
Partner code(This is
partnerCode String 15-30 private key, eMola will M
provide)
Sms will push to
smsContent String 1-180 M
customer phone
en-English
language String 2 M
pt-Portuguese
This is private key,
key String M
eMola will provide
ID that reflects in
refNo String 20 customer message to M
identify a transaction.
rawData String M

1.2. Soap Response

<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:gwOperationResponse
xmlns:ns2="http://webservice.bccsgw.viettel.com/">
<Result>
<error>0</error>
<return/>
<original>
<![CDATA[<?xml version="1.0" ?>
<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:pushUssdMessageResponse
xmlns:ns2="http://services.wsfw.vas.viettel.com/">
<return>
<errorCode>0</errorCode>
<message>Successfully</message>

7
 MOVITEL USSD PUSH API SPECIFICATION

<reqeustId>00204020210425143336</reqeustId>

</return>
</ns2:pushUssdMessageResponse>
</S:Body>
</S:Envelope>]]>
</original>
<gwtransid>20210324093455711185</gwtransid>
</Result>
</ns2:gwOperationResponse>
</S:Body>
</S:Envelope>

2. View transaction status

This api to view history of any transactions
The flow chart will be like this

2.1. Soap Request

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://webservice.bccsgw.viettel.com/">
<soapenv:Header/>
<soapenv:Body>
<web:gwOperation>
<Input>
<username>xxxxx</username>
<password>yyyyy</password>
<wscode>pushUssdQueryTrans</wscode>
<param name="partnerCode" value=""/>
<param name="transId" value=""/>
<param name="key" value=" "/>
<param name=" transType " value=" "/>
<rawData>?</rawData>
</Input>

8
 MOVITEL USSD PUSH API SPECIFICATION

</web:gwOperation>
</soapenv:Body>
</soapenv:Envelope>

Description:
Requir
Param Type Length Description
e
The request ID which is returned from each
transId String 15-30 M
transaction
partnerCode String 10 This is private key, eMola will provide M
Transaction type:
-B2C (pushUssdDisbursementB2C)
-C2B (pushUssdMessage)
transType String 3 M
-QUERY_TXN (pushUssdQueryTrans)
-QUERY_CUS (queryAccountBalance)
-QUERY_BEN (queryBeneficiaryName)
key String 20 This is private key, eMola will provide M
rawData String M

2.2. Soap Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:gwOperationResponse xmlns:ns2="http://webservice.bccsgw.viettel.com/">
<Result>
<error>0</error>
<return/>
<original><![CDATA
<?xml version="1.0" ?>
<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:pushUssdQueryTransResponse
xmlns:ns2="http://services.wsfw.vas.viettel.com/">
<return>
<errorCode>0</errorCode>
<message>Successfully</message>
<orgResponseCode>01</orgResponseCode>

9
 MOVITEL USSD PUSH API SPECIFICATION

<orgResponseMessage>01| Transaction successful

|</orgResponseMessage>
<reqeustId>00204020210425143339</reqeustId>
</return>
</ns2:pushUssdQueryTransResponse>
</S:Body>
</S:Envelope>

]]></original>
<gwtransid>20210330161708018116</gwtransid>
</Result>
</ns2:gwOperationResponse>
</S:Body>
</S:Envelope>

Detail response code (get from return tag in original tag):

Param Length Description
String(2) 0-Successful
errorCode
<>0-View in detail mesage
message String(200) Detail mesage
String(2) Response code of origin transaction
orgResponseCode
00: Error ; 01: Success

3. Disbursement Request
This Api is for B2C Disbursement Request
The flow chart will be like this

3.1. Soap Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://webservice.bccsgw.viettel.com/">
<soapenv:Header/>
<soapenv:Body>

10
 MOVITEL USSD PUSH API SPECIFICATION

<web:gwOperation>
<Input>
<username>d609baa5ba374a7e89f74f99c33ad761</username>
<password>09671efad19a4d85f2960fde2812339e</password>
<wscode>pushUssdDisbursementB2C</wscode>
<param name="partnerCode" value="00204"/>
<param name="msisdn" value=""/>
<param name="smsContent" value="remark "/>
<param name="transAmount" value=""/>
<param name="transId" value=""/>
<param name="key" value=""/>
<rawData>?</rawData>
</Input>
</web:gwOperation>
</soapenv:Body>
</soapenv:Envelope>

Description:
Param Type Length Description Require
Unique value for each
transId String 15-30 M
transaction
partnerCode String 15-30 Partner code M
msisdn of subscriber
want to push the
msisdn String 9 M
message
prefix: 86/87
The money needs to
transAmount String 1-5 M
payment
The remark of
smsContent String 1-100 transaction , default is O
partner name
This is private key,
key String 20 M
eMola will provide

3.2. Soap Response

<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>

11
 MOVITEL USSD PUSH API SPECIFICATION

<ns2:gwOperationResponse
xmlns:ns2="http://webservice.bccsgw.viettel.com/">
<Result>
<error>0</error>
<return/>
<original>
<![CDATA[
<?xml version="1.0" ?>
<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:pushUssdDisbursementB2CResponse
xmlns:ns2="http://services.wsfw.vas.viettel.com/">
<return>
<errorCode>0</errorCode>
<message>Successfully</message>
<reqeustId>00204020210425155339</reqeustId>
</return>
</ns2:pushUssdDisbursementB2CResponse>
</S:Body>
</S:Envelope>]]>
</original>
<gwtransid>20210423113728873969</gwtransid>
</Result>
</ns2:gwOperationResponse>
</S:Body>
</S:Envelope>

4. Callback function
-The function will be call to inform the partner whenever the customer approved
the transaction or exceed time.
-The detail function will be declared by the partner, but there parameters bellow
are required:

Parameter Description
reqeustId Request id generated in eMola system.
transId Transaction id of a transaction.
refNo ID that reflects in customer message to identify a transaction
errorCode Transaction status, see on detail response code
message Description

12
 MOVITEL USSD PUSH API SPECIFICATION

4.1. Request
-Payload format:
RequestMethod:POST
Content-Type: application/json

{
"reqeustId": "String",
"transId": "String",
"refNo": "String",
"errorCode": "String",
"message": "String"
}
4.2. Response

{
"ResponseCode": "0",
"ResponseMessage": "String"
}

ResponseCode =0: callback transaction success

5. Get beneficiary name

- The function to query beneficiary name in Emola system.
5.1. Soap Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://webservice.bccsgw.viettel.com/"><soapenv:Header/>
<soapenv:Body>
<web:gwOperation>
<Input>

<username>d609baa5ba374a7e89f74f99c33ad761</username>

<password>09671efad19a4d85f2960fde2812339e</password>
<wscode>queryBeneficiaryName</wscode>
<param name="transId" value=""/>
<param name="partnerCode" value=""/>
<param name="msisdn" value=""/>

13
 MOVITEL USSD PUSH API SPECIFICATION

<param name="key" value=" "/>

<rawData>?</rawData>
</Input>
</web:gwOperation>
</soapenv:Body>
</soapenv:Envelope>

Description:
Param Type Length Description Require
Unique value for each
transId String 15-30 M
transaction
partnerCode String 15-30 Partner code M
msisdn of subscriber
want to push the
msisdn String 9 M
message
prefix: 86/87
This is private key,
key String 20 M
eMola will provide

5.2. Soap Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:gwOperationResponse xmlns:ns2="http://webservice.bccsgw.viettel.com/">
<Result>
<error>0</error>
<return/>
<original><![CDATA[<?xml version="1.0" ?><S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns2:queryBeneficiaryNam
eResponse
xmlns:ns2="http://services.wsfw.vas.viettel.com/"><return><errorCode>0</errorCode><mes
sage>A*** B***
</message><reqeustId>00204020220505163228625</reqeustId></return></ns2:queryBenef
iciaryNameResponse></S:Body></S:Envelope>]]></original>
<gwtransid>202205051632296726295</gwtransid>
</Result>
</ns2:gwOperationResponse>
</S:Body>
</S:Envelope>

14
 MOVITEL USSD PUSH API SPECIFICATION

6. Check Account balance

This api to check account balance
The flow chart will be like this

6.1. Soap Request

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://webservice.bccsgw.viettel.com/">
<soapenv:Header/>
<soapenv:Body>
<web:gwOperation>
<Input>
<username>xxxxx</username>
<password>yyyyy</password>
<wscode>queryAccountBalance</wscode>
<param name="partnerCode" value=""/>
<param name="transId" value=""/>
<param name="key" value=" "/>
<rawData>?</rawData>
</Input>
</web:gwOperation>
</soapenv:Body>
</soapenv:Envelope>

15
 MOVITEL USSD PUSH API SPECIFICATION

- Description:
Requir
Param Type Length Description
e
The request ID which is
transId String 15-30 returned from each M
transaction
This is private key,
partnerCode String 10 M
eMola will provide
This is private key,
key String 20 M
eMola will provide
rawData String M

6.2. Soap Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:gwOperationResponse xmlns:ns2="http://webservice.bccsgw.viettel.com/">
<Result>
<error>0</error>
<return/>
<original><![CDATA
<?xml version="1.0" ?>
<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2: queryAccountBalanceResponse
xmlns:ns2="http://services.wsfw.vas.viettel.com/">
<return>
<errorCode>0</errorCode>
<message>Successfully</message>
< balance >1000</ balance >
<reqeustId>00204020218798943339</reqeustId>
</return>
</ns2: queryAccountBalanceResponse>
</S:Body>
</S:Envelope>

]]></original>
<gwtransid>20210330161708018116</gwtransid>
</Result>
</ns2:gwOperationResponse>

16
 MOVITEL USSD PUSH API SPECIFICATION

</S:Body>
</S:Envelope>
- Detail response code (get from return tag in original tag):
Param Length Description
String(2) 0-Successful
errorCode
<>0-View in detail mesage
message String(200) Detail mesage
balance String(15) Current account balance

C. Detail response code

Get from return tag in original tag:

0 Successfully
98 Login failed invalid user
02 Login failed.IP client not valid
03 Transaction has failed
05 Invalid partner code
06 Invalid amount
07 Invalid MSISDN
08 Text must be greater than 0 or equal to 150 characters
09 The transaction ID must be less than or equal to 50 characters
10 ISDN not in white list
11 Customer did not enter PIN
12 Customer dose not have eMola account
13 Cannot find org reqeust id
14 TransID already existed
15 Request does not exist
20 The ISDN is in other process.
22 Push message done(When asynchronous is enabled)
23 Invalid refNo
24 The function is not supported
25 Invalid LOTO service
26 Invalid LOTO number
27 Payment request not found
28 Transaction has processed
99 Have an occur while processing

17
MOVITEL USSD PUSH API SPECIFICATION

18