Technical Specification

“Recharge Using Dealer’s Inventory Stock API”

The information contained herein is the property of PT Internux and is provided on condition that
it will not be reproduced, copied, lent or disclosed, directly or indirectly, nor used for any purpose
other than that for which it was specifically furnished.

Issuing Department: CSN Planning

Document No: Date: February 20, 2014

Version: V 1.0.0 Author: Aldy Kartikahadi

Location: Jakarta Pages: 14

 Document Control & Revision History

Date Ver Revisions Author

October 23, 2013 0.9 Initial version Aldy Kartikahadi

October 25, 2013 0.9.1 Self-Signed Certificate in Security Aldy Kartikahadi

November 1, 2013 0.9.2 Removed prefix in XML RPC call example Aldy Kartikahadi

December 23, 2013 0.9.9 Add error codes listings Aldy Kartikahadi

Put information about existing optional

February 20, 2014 1.0.0 Aldy Kartikahadi
parameters in topUpRequest

Document Approvals

Approved By Signature Date

Sally Ocktovianti
I Background

The main business process described in this document is related with recharge using
inventory stock by a dealer.

II Scope

This technical specification will cover API for recharge using inventory stock by a dealer.
By using this API dealers can do recharge on behalf of a subscriber using their inventory
stock in Internux system. When recharge transaction succeed, their inventory stock in
Internux system will then be decreased.

III Requirements

a) Dealer has an account in Internux System (in the form of Dealer's MSISDN and transaction
PIN).
b) Dealer will inform the IP address of its server that will access these APIs and this IP address
will be put in the whitelist of Internux firewall.
c) Protocol used is XML-RPC. Dealer can use Java, PHP, C#.NET, PERL, Phyton, C++ or any other
language that has XML-RPC implementation to use this API.
d) Security: Secure HTTP over SSL (HTTPS). Port 8443.

IV API

1. topUpRequest

A dealer sends an XML-RPC request topUpRequest and the API will respond with the result of the
transaction.

Dealer sends an XML-RPC call with method name topUpRequest and parameters in “struct” data
type. The parameters are as follow:
Key Type Description
MSISDN String 20 Dealer’s MSISDN
REQUESTID String 20 Indicates the RequestID
of the recharge request
PIN String 20 Indicates the
transaction PIN of the
dealer
NOHP String 20 Indicates the MSISDN
of a subscriber to
recharge
NOM String 10 Nom of a recharge
product that has been
configured and mapped
to a recharge amount
in Internux system
DATETIME DateTime(iso8601 Indicates the datetime
format) of the recharge
transaction from the
 dealer’s side
CITY String 255 We can put the dealer’s
city or other
information like
dealer’s shop code
and/or branch code
that does this recharge
transaction

And Internux mediation server will reply with the following data:

Key Type Keterangan

RESPONSECODE String ‘00’ : Success
‘68’ : Pending
Other values : Fail
REQUESTID String 20 Indicates the RequestID of the
recharge request
MESSAGE String 200 Indicates the message of
recharge transaction result
SN String Indicates unique Serial Number
generated by Internux system
TRANSACTIONID String Indicates unique transaction ID
generated by Internux system

Java Client Example

XmlRpcClient client = new XmlRpcClient();

// The XML-RPC data type used by "XML-RPC server" is <struct>. In Java, this data
// type can be represented using HashMap.
HashMap<String,String> topUpRequestParams = new HashMap<String,String>();
topUpRequestParams.put("MSISDN", "6239283754");
topUpRequestParams.put("REQUESTID", "REQ03754329192838498");
topUpRequestParams.put("PIN", "5421234");
topUpRequestParams.put("NOHP", "8411100417");
topUpRequestParams.put("NOM", "IX50");
// The XmlRpcClient.execute method doesn't accept HashMap. It's either Object[] or
// List.
Object[] params = new Object[1];
params[0] = topUpRequestParams;
Object response = client.execute("topUpRequest", params);

Because of the above call, an XML-RPC client (dealer’s side) sends following message to the XML-RPC
server (Internux mediation server). Note that this is handled by client.execute(...) internally and we
have nothing to do with it.
<?xml version="1.0" encoding="iso-8859-1"?>
<methodCall>
<methodName>topUpRequest</methodName>
<params>
<param>
<value>
<struct>
<member>
 <name>MSISDN</name>
<value>
<string>6239283754</string>
</value>
</member>
<member>
<name>REQUESTID</name>
<value>

<string>REQ03754329192838498</string>
</value>
</member>
<member>
<name>PIN</name>
<value>
<string>5421234</string>
</value>
</member>
<member>
<name>NOHP</name>
<value>
<string>8411100417</string>
</value>
</member>
<member>
<name>NOM</name>
<value>
<string>IX50</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>

For the call mentioned above, server sends the following response back to the client:

<?xml version="1.0" encoding="iso-8859-1"?>

<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>RESPONSECODE</name>
<value>
<string>00</string>
</value>
</member>
<member>
<name>REQUESTID</name>
<value>
<string>
REQ03754329192838498</string>
</value>
</member>
<member>
<name>MESSAGE</name>
 <value>
<string>Topup ke 8411100417 50.000
berhasil, SN:3100912035321504980
</string>
</value>
</member>
<member>
<name>SN</name>
<value>
<string>3100912035321504980</string>
</value>
</member>
<member>
<name>TRANSACTIONID</name>
<value>
<string>90185826</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>

An example of topUpRequest with DATETIME and CITY

<?xml version="1.0" encoding="iso-8859-1"?>

<methodCall>

<methodName>topUpRequest</methodName>

<params>

<param>

<value>

<struct>

<member>

<name>MSISDN</name>

<value><string>6239283754</string></value>

</member>

<member>

<name>REQUESTID</name>

<value><string>9982411878</string></value>

</member>

<member>

<name>PIN</name>
 <value><string>5421234</string></value>

</member>

<member>

<name>NOHP</name>

<value><string>8411100417</string></value>

</member>

<member>

<name>NOM</name>

<value><string>IX25</string></value>

</member>

<member>

<name>DATETIME</name>

<value><dateTime.iso8601>20131211T14:31:18</dateTime.iso8601></value>

</member>

<member>

<name>CITY</name>

<value><string>Jakarta</string></value>

</member>

</struct>

</value>

</param>

</params>

</methodCall>

2. topUpInquiry

A dealer sends an XML-RPC request topUpInquiry for pending recharge requests and the API will
respond with the current status of the recharge transaction.

Dealer sends an XML-RPC call with method name topUpInquiry and parameters in “struct” data type.
The parameters are as follow:
Key Type Keterangan
REQUESTID String 20 Indicates the RequestID
of the pending
recharge request for
 which its status need to
be checked
MSISDN String 20 Dealer’s MSISDN

PIN String 20 Indicates the

transaction PIN of the
dealer
NOHP String 20 Indicates the MSISDN
of a subscriber for
which we want to
check his or her
recharge transaction
status

And Internux mediation server will reply with the following data:

Key Type Keterangan

RESPONSECODE String ‘00’ : Success
‘68’ : Pending
Other values : Fail
MESSAGE String 200 Indicates the message of
recharge transaction result

Java Client Example

XmlRpcClient client = new XmlRpcClient();

// The XML-RPC data type used by "XML-RPC server" is <struct>. In Java, this data
// type can be represented using HashMap.
HashMap<String,String> topUpInquiryParams = new HashMap<String,String>();
topUpInquiryParams.put("REQUESTID", "REQ03754329192838498");
topUpInquiryParams.put("MSISDN", "6239283754");
topUpInquiryParams.put("PIN", "5421234");
topUpInquiryParams.put("NOHP", "8411100417");
// The XmlRpcClient.execute method doesn't accept HashMap. It's either Object[] or
// List.
Object[] params = new Object[1];
params[0] = topUpInquiryParams;
Object response = client.execute("topUpInquiry", params);

Because of the above call, an XML-RPC client (dealer’s side) sends following message to the XML-RPC
server (Internux mediation server). Note that this is handled by client.execute(...) internally and we
have nothing to do with it.

<?xml version="1.0" encoding="iso-8859-1"?>

<methodCall>
<methodName>topUpInquiry</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>REQUESTID</name>
 <value>
<string>
REQ03754329192838498</string>
</value>
</member>
<member>
<name>MSISDN</name>
<value>
<string>6239283754</string>
</value>
</member>
<member>
<name>PIN</name>
<value>
<string>5421234</string>
</value>
</member>
<member>
<name>NOHP</name>
<value>
<string>8411100417</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>

For the call mentioned above, server sends the following response back to the client:

<?xml version="1.0" encoding="iso-8859-1"?>

<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>RESPONSECODE</name>
<value>
<string>00</string>
</value>
</member>
<member>
<name>MESSAGE</name>
<value>
<string>Topup ke 8411100417 50.000
berhasil, SN:3100912035321504980
</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
3. topUpExtendedInquiry

A dealer sends an XML-RPC request topUpExtendedInquiry for pending recharge requests and the
API will respond with the result of this recharge transaction.

Dealer sends an XML-RPC call with method name topUpExtendedInquiry and parameters in “struct”
data type. The parameters are as follow:
Key Type Keterangan
REQUESTID String 20 Indicates the RequestID
of the pending
recharge request
MSISDN String 20 Dealer’s MSISDN

PIN String 20 Indicates the

transaction PIN of the
dealer
NOHP String 20 Indicates the MSISDN
of a subscriber for
which we want to know
his or her recharge
transaction result

And Internux mediation server will reply with the following data:

Key Type Keterangan

RESPONSECODE String ‘00’ : Success
‘68’ : Pending
Other values : Fail
REQUESTID String 20 Indicates the RequestID of the
recharge request
MESSAGE String 200 Indicates the message of
recharge transaction result
SN String Indicates unique Serial Number
generated by Internux system
TRANSACTIONID String Indicates unique transaction ID
generated by Internux system

Java Client Example

XmlRpcClient client = new XmlRpcClient();

// The XML-RPC data type used by "XML-RPC server" is <struct>. In Java, this data
// type can be represented using HashMap.
HashMap<String,String> topUpExtendedInquiryParams = new HashMap<String,String>();
topUpExtendedInquiryParams.put("REQUESTID", "REQ03754329192838498");
topUpExtendedInquiryParams.put("MSISDN", "6239283754");
topUpExtendedInquiryParams.put("PIN", "5421234");
topUpExtendedInquiryParams.put("NOHP", "8411100417");
// The XmlRpcClient.execute method doesn't accept HashMap. It's either Object[] or
// List.
Object[] params = new Object[1];
params[0] = topUpExtendedInquiryParams;
Object response = client.execute("topUpExtendedInquiry", params);

Because of the above call, an XML-RPC client (dealer’s side) sends following message to the XML-RPC
server (Internux mediation server). Note that this is handled by client.execute(...) internally and we
have nothing to do with it.

<?xml version="1.0" encoding="iso-8859-1"?>

<methodCall>
<methodName>topUpExtendedInquiry</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>REQUESTID</name>
<value>
<string>
REQ03754329192838498</string>
</value>
</member>
<member>
<name>MSISDN</name>
<value>
<string>6239283754</string>
</value>
</member>
<member>
<name>PIN</name>
<value>
<string>5421234</string>
</value>
</member>
<member>
<name>NOHP</name>
<value>
<string>8411100417</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>

For the call mentioned above, server sends the following response back to the client:

<?xml version="1.0" encoding="iso-8859-1"?>

<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>RESPONSECODE</name>
<value>
<string>00</string>
</value>
 </member>
<member>
<name>REQUESTID</name>
<value>
<string>
REQ03754329192838498</string>
</value>
</member>
<member>
<name>MESSAGE</name>
<value>
<string>Topup ke 8411100417 50.000
berhasil, SN:3100912035321504980
</string>
</value>
</member>
<member>
<name>SN</name>
<value>
<string>3100912035321504980</string>
</value>
</member>
<member>
<name>TRANSACTIONID</name>
<value>
<string>90185826</string>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
V Security

The process of authenticating and establishing an encrypted channel using certificate-based mutual
authentication involves the following steps:

1. A dealer requests access to a protected resource (Internux recharge using dealer’s inventory stock
API).

2. Internux mediation server presents its certificate to the dealer.

3. The dealer verifies Internux mediation server’s certificate.

4. If successful, the dealer sends its certificate to Internux mediation server.

5. Internux mediation server verifies the dealer’s credentials.

6. If successful, Internux mediation server grants access to the protected resource requested by the
dealer (i.e. call the Internux recharge using dealer’s inventory stock API).

Note: The certificates are self-signed, but it gives us enough protection.

VI Error Codes

Response Message
Code
00 Example : Topup ke no 8419900137 sebesar 10000 rupiah berhasil, SN:
D420131114101533000002
68 Pending
-1 Fail because at least one of mandatory paramaters is missing.
-2 Fail because of non existent dealer.
-3 Fail because of duplicate Request ID from the same dealer.
-4 Fail because of non existent recharge product.
-99 Fail because of insufficient dealer's credit limit.
-999 Fail because of technical problems. Please try again later.
-9 Example: Setelah sebelumnya pending, topup ke no 8419900137 sebesar 10000
rupiah gagal.
405492878 The dealerMSISDN segment is not configured.
405492877 The DealerMSISDN does not exist.
405490738 The MSISDN segment is not configured, please configure it in Number Segment
Configuration.
405493112 The PIN is incorrect.
405491265 The MSISDN segment is not configured,please configure it in Maintain Mapping of
Brand and Number Segments.
405493037 Your account has been frozen by the administrator.
405493038 You are currently suspended.
405493004 You are not in active status.
405493072 Your account was frozen because of you entered wrong pin times more than system
limited. Please go to operator unfreeze it.
405492931 The system is busy, please try later.

Note: 405490738 or 405491265 means Subscriber No is incorrect/does not exist in the system