MegaPay

https://megapay.co.ke/documentation/
Admin
MegaPay is a payment API platform that enables developers to integrate M-Pesa payments, wallet...
Tokens:3,692
Snippets:24
Trust Score:2.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Mpesa STK Push Error Response Example

Source: https://megapay.co.ke/documentation

An example of an error response when an M-Pesa STK Push transaction encounters an issue, such as cancellation by the user. Note the 'ResponseCode' and 'ResponseDescription'.

```json
{
    "ResponseCode": 1032,
    "ResponseDescription": "Request cancelled by user",
    "MerchantRequestID": "c687-4e11-bbe3-3e2fd41c9911951313",
    "CheckoutRequestID": "ws_CO_28092024232536273769290734",
    "TransactionID": "SOFTPID2809202423253425286",
    "TransactionAmount": 640,
    "TransactionDate": "20240928232534",
    "TransactionReference": "1",
    "Msisdn": "254769290734"
}
```

--------------------------------

### Initiate Mpesa STK Push Request

Source: https://megapay.co.ke/documentation

Use this JSON payload to initiate an M-Pesa STK Push for collecting payments. Ensure all required parameters like api_key, email, amount, and msisdn are correctly provided.

```json
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "email": "example@gmail.com",
    "amount": "30",
    "msisdn": "254768783443",
    "reference": "6527990"
}
```

--------------------------------

### Test Webhook with cURL

Source: https://megapay.co.ke/documentation

Simulates a MegaPay webhook notification by sending a POST request with a JSON payload to your endpoint.

```bash
curl -X POST https://your-domain.com/webhook.php \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseCode": 0,
    "ResponseDescription": "Success. Request accepted for processing",
    "MerchantRequestID": "test-merchant-id",
    "CheckoutRequestID": "test-checkout-id",
    "TransactionID": "TEST_TRANSACTION_123",
    "TransactionAmount": 100,
    "TransactionReceipt": "TEST_RECEIPT",
    "TransactionDate": "20241201120000",
    "TransactionReference": "TEST_REF_123",
    "Msisdn": "254712345678"
  }'
```

--------------------------------

### Initiate STK Push

Source: https://megapay.co.ke/documentation

Initiates an M-Pesa STK Push to collect payments from customers. The funds are automatically sent to your linked M-Pesa till number, paybill number, or bank account.

```APIDOC
## POST /backend/v1/initiatestk

### Description
Initiates an M-Pesa STK Push to collect payments from customers. The funds are automatically sent to your linked M-Pesa till number, paybill number, or bank account.

### Method
POST

### Endpoint
https://megapay.co.ke/backend/v1/initiatestk

### Headers
- **Content-Type** (string) - Required - The Accept request HTTP header advertises which content types the client can understand. - application/json

### Parameters
#### Request Body
- **api_key** (string) - Required - API key obtained from your MegaPay Account - nluhfjdgbmzfyjrwzsbqkwcsijb
- **email** (string) - Required - Email that you use to login into PesaFlux Account - example@gmail.com
- **amount** (number) - Required - Amount to request from your customer in KES - 1
- **msisdn** (string) - Required - Phone number to request money from - 254768783443 OR 0768783443
- **reference** (string) - Optional - A unique reference that will be used to identify the transaction - 6527990

### Request Example
```json
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "email": "example@gmail.com",
    "amount": "30",
    "msisdn": "254768783443",
    "reference": "6527990"
}
```

### Response
#### Success Response (200)
- **success** (string) - Indicates the success status of the request. - 200
- **massage** (string) - A message confirming the request was sent successfully. - Request sent sucessfully.
- **transaction_request_id** (string) - A unique identifier for the transaction request. - SOFTPID2809202423523970891

#### Response Example
```json
{
    "success": "200",
    "massage": "Request sent sucessfully.",
    "transaction_request_id": "SOFTPID2809202423523970891"
}
```

#### Callback Response (Success)
- **ResponseCode** (integer) - The code indicating the status of the response. - 0
- **ResponseDescription** (string) - A description of the response. - Success. Request accepted for processing
- **MerchantRequestID** (string) - The merchant's request ID. - dab3-4cb9-9110-99918efd35e39105683
- **CheckoutRequestID** (string) - The checkout request ID. - ws_CO_28092024222014167769290734
- **TransactionID** (string) - The unique identifier for the transaction. - SOFTPID2809202422201241148
- **TransactionAmount** (number) - The amount of the transaction. - 2
- **TransactionReceipt** (string) - The transaction receipt number. - SIS88JC7AM
- **TransactionDate** (string) - The date and time of the transaction. - 20240928222012
- **TransactionReference** (string) - The reference number for the transaction. - 8803416
- **Msisdn** (string) - The phone number associated with the transaction. - 254769290734

#### Error Response Example
```json
{
    "ResponseCode": 1032,
    "ResponseDescription": "Request cancelled by user",
    "MerchantRequestID": "c687-4e11-bbe3-3e2fd41c9911951313",
    "CheckoutRequestID": "ws_CO_28092024232536273769290734",
    "TransactionID": "SOFTPID2809202423253425286",
    "TransactionAmount": 640,
    "TransactionDate": "20240928232534",
    "TransactionReference": "1",
    "Msisdn": "254769290734"
}
```

### Error Response Codes
- **0** - Success. Request accepted for processing
- **1** - The balance is insufficient for the transaction.
- **1032** - Request cancelled by user
- **1037** - DS timeout user cannot be reached
- **1025** - An error occurred while sending a push request
- **9999** - An error occurred while sending a push request.
- **2001** - The initiator information is invalid.
- **1019** - Transaction has expired
- **1001** - Unable to lock subscriber, a transaction is already in process for the current subscriber
```

--------------------------------

### Handle MegaPay Webhook in PHP

Source: https://megapay.co.ke/documentation

Processes incoming JSON webhook notifications, validates transaction data, and updates payment status in a MySQL database.

```php
<?php
// webhook.php - Handle MegaPay webhook notifications

// Get the raw POST data
$json = file_get_contents('php://input');
$data = json_decode($json, true);

// Log the webhook data for debugging
error_log("MegaPay Webhook: " . $json);

// Validate the webhook data
if (!$data || !isset($data['TransactionID'])) {
    http_response_code(400);
    echo "Invalid webhook data";
    exit;
}

// Extract transaction details
$responseCode = $data['ResponseCode'];
$transactionId = $data['TransactionID'];
$amount = $data['TransactionAmount'];
$receipt = $data['TransactionReceipt'];
$phone = $data['Msisdn'];
$reference = $data['TransactionReference'];

// Process the transaction based on response code
if ($responseCode == 0) {
    // Transaction successful
    processSuccessfulPayment($transactionId, $amount, $receipt, $phone, $reference);
    
    // Send success response
    http_response_code(200);
    echo json_encode(['status' => 'success', 'message' => 'Webhook processed']);
    
} else {
    // Transaction failed
    processFailedPayment($transactionId, $responseCode, $data['ResponseDescription']);
    
    // Send success response (acknowledge receipt)
    http_response_code(200);
    echo json_encode(['status' => 'received', 'message' => 'Failed transaction logged']);
}

function processSuccessfulPayment($transactionId, $amount, $receipt, $phone, $reference) {
    // Your business logic here
    // Example: Update database, send confirmation email, etc.
    
    // Database connection (replace with your details)
    $pdo = new PDO('mysql:host=localhost;dbname=your_db', 'username', 'password');
    
    // Update payment status in database
    $stmt = $pdo->prepare("
        UPDATE payments 
        SET status = 'completed', 
            transaction_receipt = ?, 
            completed_at = NOW() 
        WHERE transaction_id = ?
    ");
    $stmt->execute([$receipt, $transactionId]);
    
    // Send confirmation email/SMS to customer
    sendConfirmation($phone, $amount, $receipt);
}

function processFailedPayment($transactionId, $responseCode, $description) {
    // Log failed transaction
    $pdo = new PDO('mysql:host=localhost;dbname=your_db', 'username', 'password');
    
    $stmt = $pdo->prepare("
        UPDATE payments 
        SET status = 'failed', 
            failure_reason = ?, 
            failed_at = NOW() 
        WHERE transaction_id = ?
    ");
    $stmt->execute([$description, $transactionId]);
}

function sendConfirmation($phone, $amount, $receipt) {
    // Send SMS confirmation using FluxSMS API
    $message = "Payment of KES {$amount} received successfully. Receipt: {$receipt}. Thank you!";
    
    // Use FluxSMS API to send confirmation
    // Implementation depends on your SMS setup
}
?>
```

--------------------------------

### Check Mpesa Transaction Status Request

Source: https://megapay.co.ke/documentation

Submit this JSON payload to check the status of an M-Pesa STK Push transaction. You will need the 'api_key', 'email', and the 'transaction_request_id' obtained from the initiation response.

```json
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "email": "example@gmail.com",
    "transaction_request_id": "SOFTPID2809202423253425286"
}
```

--------------------------------

### Mpesa STK Push Callback Success Payload

Source: https://megapay.co.ke/documentation

This JSON represents the payload received via webhook upon a successful M-Pesa STK Push transaction. It contains detailed transaction information.

```json
{
    "ResponseCode": 0,
    "ResponseDescription": "Success. Request accepted for processing",
    "MerchantRequestID": "dab3-4cb9-9110-99918efd35e39105683",
    "CheckoutRequestID": "ws_CO_28092024222014167769290734",
    "TransactionID": "SOFTPID2809202422201241148",
    "TransactionAmount": 2,
    "TransactionReceipt": "SIS88JC7AM",
    "TransactionDate": "20240928222012",
    "TransactionReference": "8803416",
    "Msisdn": "254769290734"
}
```

--------------------------------

### Mpesa STK Push Success Response

Source: https://megapay.co.ke/documentation

This is the expected success response when an STK Push request is initiated successfully. It includes a transaction request ID for further status checks.

```json
{
    "success": "200",
    "massage": "Request sent sucessfully.",
    "transaction_request_id": "SOFTPID2809202423523970891"
}
```

--------------------------------

### Webhook Payload Structure

Source: https://megapay.co.ke/documentation

The JSON payload sent to your webhook URL via POST request upon transaction completion.

```json
{
    "ResponseCode": 0,
    "ResponseDescription": "Success. Request accepted for processing",
    "MerchantRequestID": "dab3-4cb9-9110-99918efd35e39105683",
    "CheckoutRequestID": "ws_CO_28092024222014167769290734",
    "TransactionID": "SOFTPID2809202422201241148",
    "TransactionAmount": 100,
    "TransactionReceipt": "SIS88JC7AM",
    "TransactionDate": "20240928222012",
    "TransactionReference": "ORDER_12345",
    "Msisdn": "254769290734"
}
```

--------------------------------

### Transaction Status Response

Source: https://megapay.co.ke/documentation

The JSON structure returned when querying the status of a transaction.

```json
{
    "ResultCode": "200",
    "ResultDesc": "Success. Request accepted for processing",
    "TransactionID": "SOFTPID2809202423523970891",
    "TransactionStatus": "Completed",
    "TransactionCode": "0",
    "TransactionReceipt": "SIS48OB9N4",
    "TransactionAmount": "10",
    "Msisdn": "254768783443",
    "TransactionDate": "202423491281280",
    "TransactionReference": "8803416"
}
```

--------------------------------

### Transaction Status

Source: https://megapay.co.ke/documentation

Checks the status of an M-Pesa transaction using the transaction request ID obtained after initiating an STK push.

```APIDOC
## POST /backend/v1/transactionstatus

### Description
Checks the status of an M-Pesa transaction using the transaction request ID obtained after initiating an STK push.

### Method
POST

### Endpoint
https://megapay.co.ke/backend/v1/transactionstatus

### Parameters
#### Request Body
- **api_key** (string) - Required - API key obtained from your MegaPay Account - nluhfjdgbmzfyjrwzsbqkwcsijb
- **email** (string) - Required - Email that you use to login into MegaPay Account - example@gmail.com
- **transaction_request_id** (string) - Required - Transaction id that you get after initiating stk push - SOFTPID2809202423253425286

### Request Example
```json
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "email": "example@gmail.com",
    "transaction_request_id": "SOFTPID2809202423253425286"
}
```
```
Tokens:
Raw