Nile Center for Technology Research

Governmental Payment Information System –Receipt 15

E15 CASH OFFLINE PAYMENT APIs

Specifications
Document Control

Version Date Author Description

2.3 13-04-2016 Sima Elzein Add version parameter

2.4 19-04-2016 Batool Osama Parameters justification

HmacSha256Encode method justification

2.5 30-05-2016 Batool Osama Update get update method.

Update status codes.

1
Table of Contents
Services List ...................................................................................................................................................... 3
Parameters List ................................................................................................................................................ 4
Web Services Description ................................................................................................................................ 7
API Resources and Methods ............................................................................................................................ 7
Register: ........................................................................................................................................................ 8
Request Parameters ................................................................................................................................. 8
Response Parameters .............................................................................................................................. 8
Upload: ........................................................................................................................................................ 10
Request Parameters ............................................................................................................................... 10
Response Parameters ............................................................................................................................ 11
Get Updates: ................................................................................................................................................ 12
Request Parameters ............................................................................................................................... 12
Response Parameters ............................................................................................................................ 12
Generate Ornic67: ...................................................................................................................................... 14
Resource info .......................................................................................................................................... 14
Request Parameters ............................................................................................................................... 14
Response Parameters ............................................................................................................................ 14
Glossary:.......................................................................................................................................................... 15
Conventions: ............................................................................................................................................... 15
Response Codes: ......................................................................................................................................... 15
Appendix: ........................................................................................................................................................ 18
HmacSha256Encode method: ................................................................................................................... 18
Sample Code: .......................................................................................................................................... 18
Examples of Calling HmacSha256Encode method: ............................................................................. 18

2
Services List
Service Name Service Description Method
Register terminal This service gets the terminal register
configurations from the central system
upon first deployment.

Upload terminal This service patches the transactions that upload

transactions have been recorded offline in the terminal
to the central system.

Update terminal This service gets the updates from the get_update
configurations central system.

Generate ornic67 This service is to generate ornic67 generate_ornic67

3
Parameters List
Parameter Description Type
block_status This indicates whether or not there is a command boolean
to block the terminal.

classes The subservices in a receipt. JSONArray

classes_fees Subservice’s fees. Should be a positive values double

greater than zero also it depends on “discount”,
“has_vat” and “flag” parameters values.

classes_id Subservice’s id of an existed sub service. int

classes_name Subservice’s name of an existed sub service. String

classes_no No of subservices in a receipt. int

currency The service currency which should be an existed String

currency

date E15 receipt’s issuing date date

discount To determine if there is discount. int (1 => yes,

0=>no)

editable This indicates whether or not the fees are boolean

determined.

last_receipt_offline Last receipt number generated in offline mode. String

receipt_no E15 receipt unique identifier. String

full_name User full name. string

user_id Unique identifier for the logged in user to be used string

in the process of receipt generation.

receipts Contains all receipts and their details. JSONArray

receipts_no The total number of receipts and should be equal int

to number of the receipts contained in “receipts”
array.

4
receipts_threshold The number of receipts a terminal is allowed to int
issue without connecting to the central system.

received_from The receipt’s payer name. String

response_code See Responses - table 42 int

response_message See Responses - table 42 String

seq_patching The sequence of patching transactions to the int

central system.

service_fees The fees of an existed service. double

service_id The service’s id. The service must be existed in the int
terminal unit.

service_name The service’s name. The service must be existed in String

the terminal unit.

services All services in all units. JSONArray

stamp_duty The duty of the stamp. int

terminal_id The terminal ID used to authenticate the terminal. String

Also it must be an id of existed terminal.

terminal_pass The terminal password used to authenticate the String

terminal.

time_threshold The period of time a terminal is allowed to reach int

without connecting to the central system.

total Total amount of all issued receipts. double

unit_id The id of an existed governmental unit. int

unit_name The name of an existed governmental unit. String

update_status This indicates whether or not there is an update. boolean

vat The value added tax. double

has_vat This determine if the receipt has VAT or not. boolean

5
authorization This parameter is to authorize each request and string
must be in the format: [user_id:signature]

x_e15_date This is a timestamp for the request in the format: string

[EEE MMM dd HH:mm:ss Z yyyy]

This timestamp used as part of the authorization.

Where Z is time zone for East Africa Time (For
Windows like: +0300, and for Linux like: EAT)

app_id This is an application identifier for the entity. string

version This parameter represents the services version. int

6
Web Services Description
 The web service is based on HTTP protocol using JSON MIME type.
 The response listed under ‘Responses’ for each method is success response. For any
other response check Status Code table at the end of the document.
 Path: https://[ SERVER URL]/E15/api/v2/offline_terminal/[METHOD URL]
Note: The exact SERVER URL is to be sent along with the rest of the testing setup information
via email.

API Resources and Methods

 All requests should contains the following parameters in the http header:

Type Params Values

HEAD authorization string

HEAD x_e15_date string

HEAD app_id string

 Authorization format: user_id:Signature.

 Signature: hmac_sha256(shared_key, request data + x_e15_date + user_id +
sha1(user_password)).
 shared_key: the shared key between the e15 system and vendor which will be
provided by the e15 system.
 x_e15_date: the current timestamp and it is the data to be verified and it's format (EEE
MMM dd HH:mm:ss Z yyyy).
 app_id: it is an application identifier for the entity provided by e15 system.
 See the appendix to find the sample code and an example on how to generate
signature.

7
 Register:
This service gets the terminal configurations from the central system upon first deployment.

Method POST
URL register

Request Parameters

Parameters Type Description

terminal_id (string) The terminal ID and password are used to authenticate the
terminal.
terminal_pass (string)
Form:{"terminal_id":"string","terminal_pass":"string"

 terminal_pass = user password.

 terminal_id &t erminal_pass must be sent with all clients offline requests.

Response Parameters

Parameters Type Description

services (array) This is a JSON array.
Form:
[{
services:
[{service_name : string,
service_id: integer,
editable: boolean,
service_fees: double,
currency_name: string,
currency_fraction: string,
currency_code: string,
currency_id: int,
classes_no: integer,
classes: [{
class_name: string,
class_id: integer,
class_fees: double,
percentage: int
}]
}]
8
 }]
time_threshold (int) The period of time a terminal is allowed to reach without
connecting to the central system.
Form:"time_threshold": integer
money_threshold (int) Total amount to be collected in offline
mode.Form:"money_threshold": integer
receipts_threshold Number of receipts a terminal is allowed to issue without
(int) connecting to the central system.
Form:"receipts_threshold": integer
last_receipt_offline (string) Last receipt generated in the offline mode by machine
vat (int) This is the value added tax. Form:"vat": integer
stamp_duty (int) This is the duty of the stamp. Form:"stamp_duty": integer
payment_methods (int) This is the available payment methods.
Form:"payment_methods":[{method_id:integer,
method_name:string}]
unit_name (string) Unit name of the terminal user. Form:"unit_name": string

unit_id (int) Unit identifier number. Form:"unit_id": integer

full_name (string) User full name. Form:"full_name": string

user_id (int) Unique identifier for the logged in user to be used in the
process of receipt generation. Form:"user_id": integer
This parameter represents the services version.
version (int)
Form: version: integer

response_code (int) See RESPONSES table

response_message (string) See RESPONSES table

9
Upload:
This service patches the transactions that have been recorded offline in the terminal to the
central system.
Method POST
URL upload

Request Parameters

Parameters Type Description

terminal_id (string) The terminal ID and password are used to authenticate the
terminal.
terminal_pass (string)
Form:"terminal_id":"string","terminal_pass":"string"

receipts_no (int) Total number of receipts. Form:"receipts_no": integer

receipts (array) JSON array

Form:

[{ receipt_no: string,

received_from:string,

date: string,

[Optional]description: string,

services:[{
service_id : integer,

service_fees: double

}],

total : double,

currency_id: int,

payment_method_id:int,

discount:int

}]

10
 version (int) This parameter represents the services version. Form:
"version": int

 Offline receipts_no has special sequencing format.

 Terminal generate receipts in offline mode and sends batch to the server using the
following

o {yy}{1, user id[7]}{mm}{sequence[6]}

o 15 10000001 11000001
o 15 = year =>yy
o 1 in the 8th to identify that receipt generated in offline mode
o 0000001 = user id
o 11 = month => mm
o 000001 = receipt sequence number

Response Parameters

Parameters Type Description

response_code (int) See RESPONSES table

response_message (string) See RESPONSES table

failure (array) This is a JSON array that contains receipts numbers that failed
uploading. Form:["receipt_no"]

If failure array is empty [] then all receipts are successfully uploaded.

11
 Get Updates:
This service gets the updates from the central system.

Method POST
URL get_update

Request Parameters
Request Type Description
terminal_id (string) The terminal ID and password are used to
authenticate the terminal.
terminal_pass (string)
Form:{"terminal_id":"string","terminal_pass":"string"}
version (int)

Response Parameters

Response Type Description

unit_id (int) Unit identifier number
unit_name (string) Unit name of the terminal user
update_status (bool) This shows whether or not there is an update.Form: "update_status":
boolean,
services (array) JSON array
[{services:[{
service_name : string,
service_id: integer,
editable: integer,
service_fees: double,
currency_name: string,
currency_fraction: string,
currency_code: string,
currency_id: int,
classes_no: integer,
classes:[{
class_name: string,
class_id: integer,
class_fees: double,
percentage: integer

12
 }]
}]
}]
time_threshold The period of time a terminal is allowed to reach without connecting to
(int) the central system. Form:"time_threshold": integer
money_thresho (int) Total amount to be collected in offline mode. Form:
ld "money_threshold": integer
receipts_thresh (int) This is the number of receipts a terminal is allowed to issue without
old connecting to the central system.Form:"receipts_threshold":integer
last_receipt_off (string) Last receipt generated in offline mode by
line machine.Form:"last_receipt_offline":string
(array) This is the available payment methods. This parameter takes the
payment_meth following form:
ods Form:[{"method_id": integer, "method_name": string}]

vat (int) This is the value added tax. Form:"vat": int

stamp_duty (int) This is the duty of the stamp. Form:stamp_duty:int
block_status (bool) This shows whether or not there is command to block the terminal. In
case the value was true that means the terminal should be blocked, in
case the value was false that means the terminal shouldn’t be blocked.
version (int) This parameter represents the services version. Form: version: integer

response_code (int) See RESPONSES table

response_mess (string) See RESPONSES table
age

13
Generate Ornic67:
To generate ornic67.

Resource info

Method POST
URL generate_ornic67

Request Parameters

Request Type Description

terminal_id (string) The terminal ID and password are used to
authenticate the terminal.
terminal_pass (string)
Form:{"terminal_id":"string","terminal_pass":"string"}

Response Parameters

Parameters Type Description

total (double) The total amount of ornic67
response_code (int) See RESPONSES table
response_message (string) See RESPONSES table

14
Glossary:
Conventions:

1. Terminal any kind of PoS or Portal that will access E15.

2. Terminal ID is unique identifier given to each terminal user.
3. Client users of terminals
4. All responses are in JSON format.
5. All request parameters are mandatory unless explicitly marked as [optional]

Response Codes:
Below are the response codes used in this API.

Status Code Description

200 OK

202 THIS_TRANSACTION_ALREADY_PAID

500 SYSTEM_ERROR

600 BAD_REQUEST_INSUFFICIENT_PARAMETERS

601 BAD_REQUEST_MISSING_VALUE

602 AUTHENTICATION_FAILURE

603 INVALID_UNIT

604 INVALID_APPLICATION_ID

605 INCORRECT_TOTAL

606 INVALID_SERVICE

607 INVALID_CURRENCY

608 INVALID_PAYER

609 INVALID_TRANSACTION_ID

610 INVALID_DISCOUNT_VALUE

15
611 INVALID_PAYMENT_DETAILS

612 INVALID_PAYMENT_METHOD

613 EMPTY_COMMENT

614 INVALID_DATE_FORMAT

615 FROM_DATE_SHOULD_BE_BEFORE_TO_DATE

616 INVALID_PHONE

617 INVALID_TERMINAL_ID

618 INVALID_INVOICE_NO

619 NEW_PASSWORD_DOES_NOT_MATCH_PATTERN

620 MISMATCH_IN_NEW_PASSWORD_AND_CONFIRMATION

621 SHORT_PIN

622 INSUFFICIENT_PERMISSION

623 INVALID_BANK_ID

624 MAXIMUM_TOTAL_AMOUNT_DIGITS_LENGTH_IS_10

625 STAMP_SERVICE_NOT_FOUND

626 FAILURE

627 INVALID_DATE

628 INCORRECT_AMOUNT

629 INVALID_AMOUNT_FORMAT

630 INVALID_TOTAL_AMOUNT_FORMAT

631 THIS_AMOUNT_EXCEED_AMOUNT_DUE

632 REVOKED_USER_OR_TERMINAL

633 ACCESS_DENIED

16
634 INVALID_UNIT_ID

635 INVALID_DELEGATION

636 INVALID_DELEGATE_FOR

637 VERSION_IS_UP_TO_DATE

638 SHOULD_UPDATE_VERSION

639 VERSION_NOT_EXISTS

650 INVALID_RECEIPT_ID

651 INVALID_RECEIPT_NO

652 RECEIPT_ALREADY_MARKED_FOR_DELETION

653 NO_OF_RECEIPTS_IS_INCORRECT

680 INVALID_ORNIC67_ID

681 ZERO_NEW_E15

682 SOME_RECEITS_MARKED_FOR_DELETION

690 THIS_INVOICE_ALREADY_CANCELED

691 THIS_INVOICE_ALREADY_PAID

692 THE_TERMINAL_UNIT_HAVE_NO_EXPIRATION_DATE

693 TICKET_COUNT_LARGER_THAN_TOTALAMOUNT

694 TO_DATE_SHOULD_BE_PASS_DATE

17
Appendix:
HmacSha256Encode method:
This method is used to create HmcSha256 signature encoded as base64 for Authorization. The
Users of E15 APIs should digitally sign their requests using it.
Where:
 Key parameter is the shared key (secret) that is known for E15 and the user.
 Data parameter is the data that is to be signed (Hmac) and it contains json request +
x_e15_date value.

Sample Code:
public static String HmacSha256Encode(String key, String data) {
try {
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new
SecretKeySpec(Base64.decodeBase64(key.getBytes("UTF-8")), "HmacSHA256");
sha256_HMAC.init(secret_key);
return new
String(Base64.encodeBase64(sha256_HMAC.doFinal(data.getBytes("UTF-8"))));
}catch (Exception e) {e.printStackTrace();
}
return null;
}
}

Examples of Calling HmacSha256Encode method:

HmacSha256Encode("2YYUNTOwq59B8Tw1d9U7lur5VuW4ywj3OVQSTF9MDo4=","{\
"terminal_id\”:\”123\”}" + "Wed Nov 5 16:15:00 AST 2015" + “Batool” +
“2f51ac461e84126ba0bf377b9965ac5047713d95”)

Where:

18
 "2YYUNTOwq59B8Tw1d9U7lur5VuW4ywj3OVQSTF9MDo4=" is an example for
shared_key.
 “{\"terminal_id\”: \”123}” is an example for json request.
 Batool is an example for user_id.
 “2f51ac461e84126ba0bf377b9965ac5047713d95” is an example for sha1(password).

19