Академический Документы
Профессиональный Документы
Культура Документы
(K2)
Developer User Guide
K2 - XML over HTTP(S) API
v 1.2
OVERVIEW
The K2 XML over HTTP(S) API is designed to help developers integrate third-party
applications with the Kopo Kopo System (K2). This guide provides the necessary information
required to integrate a system with K2 using a RESTful XML API that facilitates bi-directional
communication using XML. This API will work with any programming language or
Management Information System (MIS) that is capable of sending and receiving XML
documents over the HTTP(S) POST protocol. Enterprises can leverage the API to allow realtime acquisition of mobile money transactions processed via the K2 System. This document
describes how the XML commands are formatted and how HTTP(S) POST is used to send the
XML data.
Synchronous or Near Real-Time Transactions
Enterprises who want to receive their mobile money transaction details as they are
processed will utilize the XML over HTTP(S) bridge. The interface requires enterprises to
expose an XML/HTTP server that will be invoked by the services running from the K2
application.
1.) Authentication
Authentication currently supported is Basic authentication. If authentication is required,
the user name and password will have to be provided to the K2 application. If a different
authentication method such as an API key/token is desired, one should be provided.
Requirements: Basic authentication credentials (if in use)
2.) Request
The POST request will be sent to a URL provided by the enterprise. (NB: Only the http
method POST will be used). Every request will be in XML format, and hence the ContentType header will be set to application/xml. To have the MIS send an XML response, the
Accept header will also be set to application/xml. An example using curl and basic
authentication:
curl -d '@/home/K2_system/test.xml' -H 'Accept: application/xml' -H 'Content-Type: application/xml'
https://username:password@company.your_mis_system.com/receive_transactions
Remarks
Example
k2_account_id
12
k2_transaction_id
15
mm_system_id
mp_transaction_id
54445
biller_number
888555
transaction_date
26/4/11
transaction_time
1:03 PM
transaction_type
Paybill
account_number
sender_phone
first_name
John
last_name
Doe
middle_name
amount
1500
currency
The Currency
KES
M-PESA
A123333
0723456789
K.
Upon successful processing of the request, an XML response with the format below will be
expected.
Sample Response:
<?xml version = "1.0" encoding = "UTF-8"?>
<response>
<transaction_response>
<k2_account_id>12</k2_account_id>
<k2_transaction_id>5</k2_transaction_id>
<mp_transaction_id>1505</mp_transaction_id>
<status>01</status>
<description>Accepted</description>
</transaction_response>
</response>
Remarks
Example
k2_account_id
12
k2_transaction_id
15
mp_transaction_id
status
description
BS44GT66
01
Accepted
Status Codes
A status code of 01 should be returned upon successful reconciling and posting of the
transaction. Other codes are:
Code
Description
01
Accepted
02
03
Invalid Payment
Any response code greater than 01 will be flagged as an error and the corresponding
transactions will be flagged on the K2 dashboard for manual reconciliation / processing. In
addition to the status codes above, HTTP status codes will also be checked for errors. A 200
HTTP status code will signify that the transaction information was successfully sent.
Name
Meaning
200
OK
400
Bad Request
401
Unauthorized
500