# Getting Started

This API will work together with related client services to deliver push and pull services to M-PAY merchants who wish to process C2B transactions automatically.

### Pulling the API

The pull API will offer endpoints through which integrators can: 

a) Query for a single Transaction searched by Mpesa transaction-id`(`**`OC33HSAKKK`**`)` 

b) Query for multiple transactions related to a certain mobile number `(`**`254725742278`**`)`

 c) Query for multiple transactions, where the amount and date match the amount and date values supplied.

 d) Query for previously failed transactions. This will instruct the client service to try and resend any transactions that may have failed earlier.

 e) Create test notifications for testing sandbox API and listening endpoints

{% hint style="info" %}
**Good to Know**: In all cases, transactions that happened more than 24 hours before will be ignored. API will return a maximum of 10 records at a time to avoid network congestion.
{% endhint %}

The push service will forward new transactions to the URLs provided by the merchant. If the provided URL is not available at that particular moment, the transaction will be marked as failed but can be resent as described in c) above.

The base URL is `http://40.114.209.253:87/`

### Push Service

The push service will POST new transactions as JSON to the https-secured URL provided by the merchant. If the merchant URL is not available at the POSTing moment, the transaction will be marked as failed but can be resent as described in the [`Query Failed Notification API`](/query-failed-notifications.md). Below is the JSON format.

```json
{
"SalmansId": "12456",
"TransactionType": 
"Customer Merchant Payment", 
"TransID": "OAH3FEH5DT", 
"TransTime": "20200804120859",
"TransAmount": "300.00", 
"BusinessShortCode": "12345",
"BillRefNumber": "WATER",
"OrgAccountBalance": "0.25",
"MSISDN": "0702021629",
"FirstName": "John",
"MiddleName": "Doe",
"LastName": "John", 
"CreatedOn": "2020-08-03 12:10:50.487000"
}
```

A **successful** response will have the following body

```json
{
  "ResultCode" : 0,
  "ResultDescr": "Success"
}
```

And a Failed response will have the following body:

```json
{
    "ResultCode": 1, 
    "ResultDescr": "Error Description"
}
```

{% hint style="info" %}
The **`ResultCode`** value is a response is a numeric status code that indicates the status of the transaction processing. 0 means successful processing and any other code means an error occured or the transaction failed.
{% endhint %}

{% hint style="info" %}

The **`ResultDescr`**  value is a response describing the status of the transaction. A string with the message "Success or transaction has failed".
{% endhint %}

### Header Parameters

Requests made on the base Url must use the following **header info**:

<table><thead><tr><th width="204">Parameter name</th><th>Description</th><th width="150">Sample Value</th></tr></thead><tbody><tr><td>Content-Type</td><td>Indicates the original media <strong>type</strong> of the resource (prior to any <strong>content</strong> encoding applied for sending.</td><td>application/json</td></tr><tr><td>ShortCode</td><td>A shortcode is a unique number that is allocated to a pay bill or buys goods organization through they will be able to receive customer payment. It could be a Pay bill, Buy Goods, or Till Number.</td><td>835625***</td></tr><tr><td>UnixTime</td><td>This is the Timestamp of the transaction, normally in the format of YEAR+MONTH+DATE+HOUR+MINUTE+SECOND (<strong>YYYYMMDDHHMMSS</strong>).</td><td>1607590160***</td></tr><tr><td>Authorization</td><td>Basic Auth over HTTPS, this is a <strong>base64 encoded</strong> string of an app's consumer key and consumer secret</td><td>base64.encode(Shortcode+Passkey+Timestamp)</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs2.m-pay.co.ke/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.