xml over http v1.2 - 04 november 2011
DESCRIPTION
XML over HttpTRANSCRIPT
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 real-time 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 “Content-Type” 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:[email protected]_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 M-PESA
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
A123333
sender_phone The phone number of the sender 0723456789
first_name The sender's first name John
last_name The sender's last name Doe
middle_name The Sender's middle name K.
amount The transaction amount 1500
currency The Currency KES
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
BS44GT66
status The status code 01
description Status code description 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>