Post on 16-Oct-2020
transcript
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
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
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":"bryana_graham@schambergerryan.net","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,
Property name Type Required Description
client_transaction_id
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,
Property name Type Required Description
client_transaction_id
string optional The optional client transaction ID same as therequest
server_transaction_id
string required The generated server transaction ID
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":"leola.bernier@haneconn.com","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":"leola.bernier@haneconn.com", "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.
4.2.1.RequestThe request has following properties,
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,
Property name Type Required Description
client_transaction_id
string optional The optional client transaction ID
4.2.2.ResponseIf the bill is sent successfully, it will return 200 OKThe response body has following attribute,
Property name Type Required Description
client_transaction_id
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
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":"leola.bernier@haneconn.com", "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.
4.3.1.RequestThe request has following properties,
API path /api/v1/merchant/e_bills/:bill_id/process.json
The :bill_id is the bill_id of the bill
HTTP verb PUT
16
The request body has following attributes,
Property name Type Required Description
client_transaction_id
string optional The optional client transaction ID
4.3.2.ResponseIf the bill is sent successfully, it will return 200 OKThe response body has following attribute,
Property name Type Required Description
client_transaction_id
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
4.3.3.SampleThe send sample is as following, the bill_id of the bill is 5550000001,
PUT /api/v1/merchant/e_bills/5550000001/process.json HTTP/1.1
{"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":"leola.bernier@haneconn.com", "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.
4.4.1.RequestThe request has following properties,
API path /api/v1/merchant/e_bills/:bill_id.json
The :bill_id is the bill_id of the bill
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
4.4.3.SampleThe send sample is as following, the bill_id of the bill is 5550000001,
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":"leola.bernier@haneconn.com", "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.
4.5.1.RequestThe request has following properties,
API path /api/v1/merchant/e_bills.json
HTTP verb GET
The request could append following query parameters,
Property name Type Required Description
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
4.5.2.ResponseIf the bill is sent successfully, it will return 200 OKThe response body has following attribute,
Property name Type Required Description
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
The sample response is as following,
HTTP/1.1 200 OK
{"current_page":2,"per_page":2,"total_entries":5,"entries":[ { "bill_id":"5550000003", "payer_id":"6469248247", "payer_email":"leanne@hoppe.biz", "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":"nicola_boyer@batz.biz", "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.
5.1.1.RequestThe request has following properties,
API path /api/v1/payment_gateway/e_bills/:bill_id/pay.json
The :bill_id is the bill_id of the bill
HTTP verb PUT
The request body has following attributes,
Property name Type Required Description
client_transaction_id
string optional The optional client transaction ID
5.1.2.ResponseIf the bill is sent successfully, it will return 200 OKThe response body has following attribute,
Property name Type Required Description
client_transaction_id
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
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"}
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":"leola.bernier@haneconn.com", "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.
5.2.1.RequestThe request has following properties,
API path /api/v1/payment_gateway/e_bills/:bill_id/verify.json
23
The :bill_id is the bill_id of the bill
HTTP verb PUT
The request body has following attributes,
Property name Type Required Description
client_transaction_id
string optional The optional client transaction ID
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,
Property name Type Required Description
client_transaction_id
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 bill verification is failed, it will return an error response, and has following properties in body,
Property name Type Required Description
client_transaction_id
string optional The optional client transaction ID same as therequest
server_transaction_id
string required The generated server transaction ID
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":"leola.bernier@haneconn.com", "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.
5.3.1.RequestThe request has following properties,
API path /api/v1/merchant/e_bills/:bill_id.json
The :bill_id is the bill_id of the bill
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
5.3.3.SampleThe send sample is as following, the bill_id of the bill is 5550000001,
GET /api/v1/merchant/e_bills/5550000001.json HTTP/1.1
The sample response is as following,
HTTP/1.1 200 OK
{ "bill_id":"5550000001", "payer_id":"4362752893", "payer_email":"leola.bernier@haneconn.com", "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