Kopo Kopo, Inc.

(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

With the url https://company.your_mis_system.com/receive_transactions having been

provided to K2.
The SML data will be in the following format:

Sample XML POST Data

<?xml version="1.0" encoding="UTF-8"?>
<transactions xmlns="http://www.kopokopo.com/schemas/k2httpxml.xsd">
<transaction_record>
<k2_account_id>12</k2_account_id>
<k2_transaction_id>5</k2_transaction_id>
<mm_system_id>M-PESA</mm_system_id>
<mp_transaction_id>1505</mp_transaction_id>
<biller_number>555555</biller_number>
<transaction_date>2011-06-06</transaction_date>
<transaction_time>1:30PM</transaction_time>
<transaction_type>Paybill</transaction_type>
<account_number>0123456789</account_number>
<sender_phone>0723456789</sender_phone>
<first_name>John</first_name>
<middle_name>S.</middle_name>
<last_name>Karanja</last_name>
<amount>2100</amount>
<currency>KES</currency>
</transaction_record>
</transactions>

A description of the fields is detailed below:

Parameter

Remarks

Example

k2_account_id

The Account Id within the K2 system

12

k2_transaction_id

The K2 assigned transaction id

15

mm_system_id

The Mobile Money System id

mp_transaction_id

The transaction is assigned to this transaction by

the Mobile Payment System

54445

biller_number

The Paybill phone number of the biller

888555

transaction_date

The Date of the transaction

26/4/11

transaction_time

The transaction time

1:03 PM

transaction_type

They type of transaction

Paybill

account_number

The account number of the subscriber within

the enterprise MIS

sender_phone

The phone number of the sender

first_name

The sender's first name

John

last_name

The sender's last name

Doe

middle_name

The Sender's middle name

amount

The transaction 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>

Response fields explanation:

Parameter

Remarks

Example

k2_account_id

The Account Id within the K2 system

12

k2_transaction_id

The K2 assigned transaction id

15

mp_transaction_id

The Confirmation number that was provided by

the Mobile Money provider for the transaction

status

The status code

description

Status code 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

Account not Found

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.

HTTP Status Codes:

Code

Name

Meaning

200

OK

Standard response for successful HTTP requests

400

Bad Request

Bad syntax in the request

401

Unauthorized

Username and/or password is incorrect. The session could not be

authenticated

500

Internal Server Error

A generic error message, given when no more specific message is

suitable

The XML Shchema for the POST data XML is as follows:

<?xml version="1.0" encoding="utf-8"?>

<xs:schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
version="1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.kopokopo.com/schemas/k2httpxml.xsd"
xmlns="http://www.kopokopo.com/schemas/k2httpxml.xsd">
<xs:annotation>
<xs:documentation xml:lang="en">
XML over HTTP Schema for K2 XML-HTTP POST Notification.
Copyright 2011, Kopo Kopo, Inc. All rights reserved.
</xs:documentation>
</xs:annotation>
<xs:element name="transactions" type="transactionsType" />
<xs:complexType name="transactionsType">
<xs:sequence>
<xs:element name="transaction_record" type="transaction_recordType" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="transaction_recordType">
<xs:sequence>
<xs:element name="k2_account_id" type="xs:int" />
<xs:element name="k2_transaction_id" type="xs:int" />
<xs:element name="mm_system_id" type="xs:string" />
<xs:element name="mp_transaction_id" type="xs:string" />
<xs:element name="biller_number" type="xs:int" />
<xs:element name="transaction_date" type="xs:dateTime" />
<xs:element name="transaction_time" type="xs:dateTime" />
<xs:element name="transaction_type" type="xs:string" />
<xs:element name="account_number" type="xs:string" />
<xs:element name="sender_phone" type="xs:string" />
<xs:element name="first_name" type="xs:string" />
<xs:element name="middle_name" type="xs:string" />
<xs:element name="last_name" type="xs:string" />
<xs:element name="amount" type="xs:decimal" />
<xs:element name="currency" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:schema>

The Schema for the XML response expected is:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
version="1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.kopokopo.com/schemas/k2httpxmlresp.xsd"
xmlns="http://www.kopokopo.com/schemas/k2httpxmlresp.xsd"
>
<xs:annotation>
<xs:documentation xml:lang="en">
XML over HTTP Schema for K2 XML-HTTP POST Notification.
Copyright 2011, Kopo Kopo, Inc. All rights reserved.
</xs:documentation>
</xs:annotation>
<xs:element name="response" type="responseType" />
<xs:complexType name="responseType">
<xs:sequence>
<xs:element name="transaction_response" type="transaction_responseType" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="transaction_responseType">
<xs:sequence>
<xs:element name="k2_account_id" type="xs:int" />
<xs:element name="k2_transaction_id" type="xs:int" />
<xs:element name="mp_transaction_id" type="xs:string" />
<xs:element name="status" type="xs:int" />
<xs:element name="description" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:schema>