ebilling rest api specification v1 · 2019. 11. 3. · 1.introduction 1.1.purpose this...

EBilling REST API Specificationv1.0

1

1. Introduction1.1. Purpose1.2. Scope

2. System Overview2.1. Functional overview2.2. Use case view2.3. AM Integration with EBilling

3. REST interface technical information3.1. Introduction3.2. Current version3.3. API URL3.4. HTTP Verbs3.5. JSON3.6. DATETIME3.7. Authentication3.8. Errors

3.8.1. Authentication failure3.8.2. Authorization failure3.8.3. eBill not found3.8.4. Business error

3.9. eBill4. Merchant API specification

4.1. Create eBill4.1.1. Request4.1.2. Response4.1.3. Sample

4.2. Send eBill4.2.1. Request4.2.2. Response4.2.3. Sample

4.3. Process eBill4.3.1. Request4.3.2. Response4.3.3. Sample

4.4. Get eBill4.4.1. Request4.4.2. Response4.4.3. Sample

4.5. Get eBills4.5.1. Request4.5.2. Response4.5.3. Sample

2

5. Payment Gateway API5.1. Pay eBill

5.1.1. Request5.1.2. Response5.1.3. Sample

5.2. Verify eBill5.2.1. Request5.2.2. Response5.2.3. Sample

5.3. Get eBill5.3.1. Request5.3.2. Response5.3.3. Sample

3

1. Introduction

1.1. PurposeThis specification defines and documents the eBilling REST API for the EBilling Systemdesigned by World Innovation Technologies, LLC. The eBilling Admin Interface provides themeans for thirdparty actors to programmatically manage eBills service.

1.2. ScopeThis document specifies the eBilling Admin Interface for the eBilling System. Informationdocumented in this specification includes generic transaction sequences, data structures, datadescriptions and REST API usage.

2. System Overview

2.1. Functional overviewThe eBilling REST Interface is divided into 2 parts:

1. Merchant API:● Allows external thirdparty systems create bill on the eBilling System.● Allows external thirdparty systems send bill to enduser via SMS or email, and

update the bill status to READY● Allows external thirdparty systems process bill by updating bill state to

PROCESSED.● A mechanism by which the eBilling System delivers query responses to external

thirdparty systems, not only unitary query but also query all bills belongs to theexternal thirdparty system.

2. Payment Gateway API:● Allows external thirdparty systems to verify bill by checking payeeID,amount info.● Allows external thirdparty systems to pay bill by updating bill state to PAID on the

eBilling System.● Allows external thirdparty systems to get the information of a bill

2.2. Use case view4

The use case view represents a highlevel illustration of the interactions of the eBilling SystemAdmin Interface.

The basic business flow is as the following diagram,

An external system initiates an eBilling creation request.1. A provisioning request is sent to the eBilling System for processing.2. The eBilling System classifies the request and proceeds accordingly. Once processing

has completed, the eBilling System sends a SMS notification to the payer.3. Payer initiates a payment request to external system, Airtel Money for instance, via SMS

or USSD.4. External system send verify request to eBilling System to verify the payment information:

billID, payerID, payeeID, amount. The eBilling System confirms the payment request.5. External system process the payment request6. Once payment done, external system sends update request to eBilling System to

update the eBill to PAID7. Later on, provisioning system can query EBilling system for status of eBill

5

2.3. AM Integration with EBilling

6

3. REST interface technical information

3.1. IntroductionRepresentational state transfer (REST) is an architectural style consisting of a coordinated setof constraints applied to components, connectors, and data elements, within a distributedhypermedia system. The REST architectural style was developed by W3C TechnicalArchitecture Group (TAG) in parallel with HTTP 1.1, based on the existing design of HTTP 1.0.

3.2. Current versionThe eBilling REST API is versioned and the current version is v1.

3.3. API URLAll API access is over HTTPS. And the entry point for all API is under the URLhttps://billingeasy.com/api/v1/ . The v1 represents the API version number. For the URL of eachAPI, it will be described in later chapters.

3.4. HTTP VerbseBilling REST API uses different HTTP verbs to differentiate the actions the client wants toperform. Currently it utilizes 3 HTTP verbs.

Verb Description

GET Get a bill or a list of bills

POST Create a bill

PUT to update or verify a bill, for example, set a bill state toPROCESSED or PAID

3.5. JSONThe REST API uses JSON format to encode the HTTP request and response. When the clientsends a HTTP request to the server, the server expects the body is of JSON format. And whenthe client receives the HTTP response, if the response has body, it should also parse the bodyas JSON format.

7

https://www.google.com/url?q=https%3A%2F%2Fbilling-easy.com%2Fapi%2Fv1%2F&sa=D&sntz=1&usg=AFQjCNEzQs1eR0sUvtr_Smqjd2oWZ7-NWg

3.6. DATETIMEAll DATETIME and timestamps are returned in ISO 8601 format: YYYYMMDDTHH:MM:SSZ

3.7. Authentication

The eBilling REST API uses HTTP Basic authentication method to do authentication. Theusername and password are encoded as Base64 and sent as a HTTP header. The steps is asfollowing,

1. Username and password are combined into a string "username:password"2. The resulting string literal is then encoded using the RFC2045MIME variant of Base643. The authorization method and a space i.e. "Basic " is then put before the encoded string.

The following example shows a encoded HTTP header,

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

3.8. Errors

If something error happens during the processing of the request, such as invalid credentials orthe client doesn’t have the right to perform an action, the server will return a error JSONresponse to the client. Different errors will return a different HTTP response code. And in theresponse body, there will be a message attribute to represent a human readable error message.

Currently the REST API will return the following type of errors,

3.8.1.Authentication failure

If the user sends invalid username or password, it will return 401 Unauthorized:

HTTP/1.1 401 Unauthorized

{ "message": "Invalid username or password"}

8

http://www.google.com/url?q=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FString_literal&sa=D&sntz=1&usg=AFQjCNHeCrmn8UbPZwexiciWZ1Szk3yNrg

http://www.google.com/url?q=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FBase64&sa=D&sntz=1&usg=AFQjCNFBXL8z0E0DI1EBVFe0p1xFhqM-nQ

3.8.2.Authorization failure

If the username/password is correct, but the user has no right to call the API, it will return 403Forbidden.

HTTP/1.1 403 Forbidden

{ "message": "No right to perform this action"}

3.8.3.eBill not found

If the eBill is not found for the bill_id, it will return 404 Not found

HTTP/1.1 404 Not found

{ "message": "The eBill is not found"}

3.8.4.Business error

If the user has the right to call the API but he inputs invalid parameters, it will return 422Unprocessable Entity, and there is a errors attribute in the response body to indicate with fieldis wrong.

The following example shows an error reponse for payment gateway’s verify API, that theamount doesn’t match,

HTTP/1.1 422 Unprocessable Entity

{ "client_transaction_id":null, "server_transaction_id":"0000000000002", "message":"The request is not processable", "errors":{ "amount":["The Amount is not matched"] }

9

}

the errors attribute is a JSON object, the key is the attribute that has error, and the value is anarray, and each element in the array is an error message on that attribute.

3.9. eBill

A lot of API will return an e_bill attribute, so the eBill is introduced here, an e_bill attribute will havefollowing properties,

Property name Type Description

bill_id string The bill ID, the length is between 10 to 16 charactersand starts with 555

payer_id string The MSISDN of the payer

payer_email string The email of the payer

payee_id string The MSISDN of the payee

payee_name string The username of the payee

amount integer The amount of the bill

currency string The currency, it’s 3 characters such as XAF, USD

state string the state of eBill, it could have following states,● created: when the bill is first created● ready: when the SMS is sent to the payer● paid: when the payer paid● processed: when it’s processed● failed: when it’s failed● cancelled: when the bill is cancelled● expired: when the bill is expired

created_at string the datetime that it’s created

updated_at string the datetime that it’s last updated

expire_at string the datetime to expire it

schedule_at string the date that SMS is sent, if it’s null, the SMS is sentimmediately after it’s created

external_reference string the merchant internal reference

10

due_date string the due date, it follows yyyymmdd format

additional_info string additional information

short_description string the short description

description string the description

reason string the reason if the bill is failed or cancelled

The following example shows a sample e_bill attribute,

{"bill_id":"5550000005","payer_id":"8505772915","payer_email":"[email protected]","payee_id":"2213206709","payee_name":"merchant","amount":31020,"currency":"SGD","state":"created","created_at":"20131229T17:17:11.259+08:00","expire_at":null,"schedule_at":null,"updated_at":"20131229T17:17:11.259+08:00","short_description":"short_description","due_date":"20131031","external_reference":null,"additional_info":null,"description":null,"reason":null}

11

4. Merchant API specification

4.1. Create eBillThe Create eBill is to create a bill in the eBilling system.

4.1.1.RequestThe request has following properties,

API path /api/v1/merchant/e_bills.json

HTTP verb POST

The Request body could have following attributes,

Property name Type Required Description

client_transaction_id

string optional The optional client transaction ID

payer_id string required the MSISDN of the payer

payer_email string optional the email of the payer

amount integer required the amount of the bill

currency string optional the currency, if not specified the default is ‘XAF’

due_date string required the due date

short_description string required the short description

description string optional the full description

merchant_internal_ref

string optional the merchant internal ref

expire_at string optional the datetime if the client wants the bill to expireat a certain datetime

12

4.1.2.ResponseIf the bill is created successfully, it will return 201 createdThe response body has following attribute,



string optional The optional client transaction ID same as therequest

server_transaction_id

string required The generated server transaction ID

e_bill eBill required The eBill, refer to the eBill chapter

If the client sends invalid parameters, it will return a response which has following attributes,






message string required The human readable error message

errors errors required The attributes that has errors, refer to the Errorschapter

4.1.3.Samplea request sample is like followingPOST /api/v1/merchant/e_bills.json HTTP/1.1

{"client_transaction_id":"001","payer_email":"[email protected]","payer_msisdn":"9086712208","amount":100,"short_description":"short_description","currency":"XAF","due_date":"20131031","payer_id":"4362752893","expire_at":"20130724T13:51:2904:00","merchant_internal_ref":"internalref001","description":"description"

13

}

A response sample is as following,

HTTP/1.1 201 Created

{"client_transaction_id":"001","server_transaction_id":"0000000000001","e_bill":{ "bill_id":"5550000001", "payer_id":"4362752893", "payer_email":"[email protected]", "payee_id":"9016529699", "payee_name":"merchant", "amount":100, "currency":"XAF", "state":"created", "created_at":"20131229T18:03:10.009+08:00", "expire_at":"20130725T01:51:29.000+08:00", "schedule_at":null, "updated_at":"20131229T18:03:10.009+08:00", "short_description":"short_description", "due_date":"20131031", "external_reference":null, "additional_info":null, "description":"description", "reason":null }}

If the client doesn’t specify amount, the response is as following,

HTTP/1.1 422 Unprocessable entity

{"client_transaction_id":"12345","server_transaction_id":"0000000000001","message":"The request is not processable","errors":{ "amount":["can't be blank","is not a number"] }}

14

4.2. Send eBillThe Send eBill API is to send SMS to the payer. When send a ebill, the bill state should becreated, and after the send, the state becomes ready.


API path /api/v1/merchant/e_bills/:bill_id/send.json

The :bill_id is the bill_id of the bill

HTTP verb PUT

The request body has following attributes,




4.2.2.ResponseIf the bill is sent successfully, it will return 200 OKThe response body has following attribute,







4.2.3.SampleThe send sample is as following, the bill_id of the bill is 5550000001,

PUT /api/v1/merchant/e_bills/5550000001/send.json HTTP/1.1

{

15

"client_transaction_id":"001"}

A successful sample is as following,

HTTP/1.1 200 OK

{"client_transaction_id":"001","server_transaction_id":"0000000000001","e_bill":{ "bill_id":"5550000001", "payer_id":"4362752893", "payer_email":"[email protected]", "payee_id":"9016529699", "payee_name":"merchant", "amount":100, "currency":"XAF", "state":"ready", "created_at":"20131229T18:03:10.009+08:00", "expire_at":"20130725T01:51:29.000+08:00", "schedule_at":null, "updated_at":"20131229T18:03:10.009+08:00", "short_description":"short_description", "due_date":"20131031", "external_reference":null, "additional_info":null, "description":"description", "reason":null }}

4.3. Process eBillThe Process eBill is to process a eBill, after processing the state of the bill is processed.


API path /api/v1/merchant/e_bills/:bill_id/process.json


HTTP verb PUT

16













PUT /api/v1/merchant/e_bills/5550000001/process.json HTTP/1.1

{"client_transaction_id":"001"}


HTTP/1.1 200 OK

{"client_transaction_id":"001","server_transaction_id":"0000000000001","e_bill":{ "bill_id":"5550000001", "payer_id":"4362752893", "payer_email":"[email protected]", "payee_id":"9016529699",

17

"payee_name":"merchant", "amount":100, "currency":"XAF", "state":"processed", "created_at":"20131229T18:03:10.009+08:00", "expire_at":"20130725T01:51:29.000+08:00", "schedule_at":null, "updated_at":"20131229T18:03:10.009+08:00", "short_description":"short_description", "due_date":"20131031", "external_reference":null, "additional_info":null, "description":"description", "reason":null }}

4.4. Get eBillThe Get eBill API is to get information of an individual bill.


API path /api/v1/merchant/e_bills/:bill_id.json


HTTP verb GET

4.4.2.ResponseIf the bill is sent successfully, it will return 200 OKThe response body is just an eBill, refers to the eBill chapter


GET /api/v1/merchant/e_bills/5550000001.json HTTP/1.1

The sample response is as following,

18

HTTP/1.1 200 OK

{ "bill_id":"5550000001", "payer_id":"4362752893", "payer_email":"[email protected]", "payee_id":"9016529699", "payee_name":"merchant", "amount":100, "currency":"XAF", "state":"processed", "created_at":"20131229T18:03:10.009+08:00", "expire_at":"20130725T01:51:29.000+08:00", "schedule_at":null, "updated_at":"20131229T18:03:10.009+08:00", "short_description":"short_description", "due_date":"20131031", "external_reference":null, "additional_info":null, "description":"description", "reason":null}

4.5. Get eBillsThe Get eBills is to get a list of bills. The bills are sorted by create_at attribute. The most recenteBills will be returned first.


API path /api/v1/merchant/e_bills.json

HTTP verb GET

The request could append following query parameters,


page integer optional the page number, which starts from 1. If notspecified it will return first page

per_page integer optional the number of bills returned, this value shouldbe bigger than 0, if not specified, by default itreturns 20 bills

19



current_page integer required The current page, it’s the same as the pagequery param if it’s specified

per_page integer required The number of bills returned

total_entries integer required The total number of bills in system

entries array requried an array of eBill. Refer to the eBill section.

4.5.3.SampleHere is a sample request to get a list of eBills, it returns page 2 and each page has two bills.

GET /api/v1/merchant/e_bills.json?page=2&per_page=2 HTTP/1.1


HTTP/1.1 200 OK

{"current_page":2,"per_page":2,"total_entries":5,"entries":[ { "bill_id":"5550000003", "payer_id":"6469248247", "payer_email":"[email protected]", "payee_id":"3739513810", "payee_name":"merchant", "amount":18960, "currency":"SGD", "state":"created", "created_at":"20131229T19:22:51.797+08:00", "expire_at":null, "schedule_at":null, "updated_at":"20131229T19:22:51.797+08:00", "short_description":"short_description",

20

"due_date":"20131031", "external_reference":null, "additional_info":null, "description":null, "reason":null },

{ "bill_id":"5550000002", "payer_id":"3784311563", "payer_email":"[email protected]", "payee_id":"3739513810", "payee_name":"merchant", "amount":38924, "currency":"SGD", "state":"created", "created_at":"20131229T19:22:51.791+08:00", "expire_at":null, "schedule_at":null, "updated_at":"20131229T19:22:51.791+08:00", "short_description":"short_description", "due_date":"20131031", "external_reference":null, "additional_info":null, "description":null, "reason":null }]}

21

5. Payment Gateway API

5.1. Pay eBillThe Pay eBill is to set a bill state to paid. Before calling this API the state of the bill should beready.


API path /api/v1/payment_gateway/e_bills/:bill_id/pay.json


HTTP verb PUT












5.1.3.SampleThe sample is as following, the bill_id of the bill is 5550000001,

22

PUT /api/v1/payment_gateway/e_bills/5550000001/pay.json HTTP/1.1

{"client_transaction_id":"001"}


HTTP/1.1 200 OK

{"client_transaction_id":"001","server_transaction_id":"0000000000001","e_bill":{ "bill_id":"5550000001", "payer_id":"4362752893", "payer_email":"[email protected]", "payee_id":"9016529699", "payee_name":"merchant", "amount":100, "currency":"XAF", "state":"paid", "created_at":"20131229T18:03:10.009+08:00", "expire_at":"20130725T01:51:29.000+08:00", "schedule_at":null, "updated_at":"20131229T18:03:10.009+08:00", "short_description":"short_description", "due_date":"20131031", "external_reference":null, "additional_info":null, "description":"description", "reason":null }}

5.2. Verify eBillThe Verify eBill is to verify a eBill.


API path /api/v1/payment_gateway/e_bills/:bill_id/verify.json

23


HTTP verb PUT





payee_id string required The payee MSISDN

amount integer required The amount to verify

5.2.2.ResponseIf the bill is verified successfully, it will return 200 OKThe response body has following attribute,







If the bill verification is failed, it will return an error response, and has following properties in body,






message string required The human readable error message

errors errors required The attributes that has verification errors, referto the Errors chapter

24

5.2.3.SampleA sample HTTP request is as following,

PUT /api/v1/payment_gateway/e_bills/5550000001/verify.json HTTP/1.1

{"client_transaction_id":"001","amount":100,"payee_id":"93793739"}

The correct response is as following,

HTTP/1.1 200 OK

{"client_transaction_id":"001","server_transaction_id":"0000000000001","e_bill":{ "bill_id":"5550000001", "payer_id":"4362752893", "payer_email":"[email protected]", "payee_id":"9016529699", "payee_name":"merchant", "amount":100, "currency":"XAF", "state":"ready", "created_at":"20131229T18:03:10.009+08:00", "expire_at":"20130725T01:51:29.000+08:00", "schedule_at":null, "updated_at":"20131229T18:03:10.009+08:00", "short_description":"short_description", "due_date":"20131031", "external_reference":null, "additional_info":null, "description":"description", "reason":null }}

If the amount is not correct, it returns a following response,

HTTP/1.1 422 Unprocessable entity

25

{"client_transaction_id":"001","server_transaction_id":"0000000000002","message":"The request is not processable","errors":{ "amount":["The Amount is not matched"] }}

5.3. Get eBillThe Get eBill API is to get information of an individual bill.


API path /api/v1/merchant/e_bills/:bill_id.json


HTTP verb GET

5.3.2.ResponseIf the bill is sent successfully, it will return 200 OKThe response body is just an eBill, refers to the eBill chapter


GET /api/v1/merchant/e_bills/5550000001.json HTTP/1.1


HTTP/1.1 200 OK

{ "bill_id":"5550000001", "payer_id":"4362752893", "payer_email":"[email protected]", "payee_id":"9016529699", "payee_name":"merchant",

26

"amount":100, "currency":"XAF", "state":"processed", "created_at":"20131229T18:03:10.009+08:00", "expire_at":"20130725T01:51:29.000+08:00", "schedule_at":null, "updated_at":"20131229T18:03:10.009+08:00", "short_description":"short_description", "due_date":"20131031", "external_reference":null, "additional_info":null, "description":"description", "reason":null}

27

ebilling rest api specification v1 · 2019. 11. 3. · 1.introduction 1.1.purpose this...

Documents