C2B Operations

C2B (Customer to Business) operations allow you to receive payments from customers directly to your M-Pesa business account. This is useful for scenarios like bill payments, product purchases, or any other customer-to-business transactions.

Basic Usage

use MesaSDK\PhpMpesa\Mpesa;
use MesaSDK\PhpMpesa\Config;
 
$config = new Config();
$config->setBaseUrl("https://apisandbox.safaricom.et")
    ->setConsumerKey("your_consumer_key")
    ->setConsumerSecret("your_consumer_secret")
    ->setEnvironment('sandbox')
    ->setShortCode("your_shortcode");
 
$mpesa = new Mpesa($config);
 
// Register C2B URLs
$result = $mpesa
    ->setValidationUrl("https://your-domain.com/validate")
    ->setConfirmationUrl("https://your-domain.com/confirm")
    ->register();
 
if ($result->isSuccessful()) {
    echo "URLs registered successfully";
} else {
    echo "Error: " . $result->getErrorMessage();
}
 
// Simulate C2B payment
$simulation = $mpesa
    ->setPhoneNumber("254712345678")
    ->setAmount(100.00)
    ->setBillReference("Bill123")
    ->setBillReferenceNumber("REF123")
    ->simulate();
 
if ($simulation->isSuccessful()) {
    echo "Simulation successful";
} else {
    echo "Error: " . $simulation->getErrorMessage();
}

Configuration

Before using C2B operations, ensure you have configured:

Shortcode: Your M-Pesa shortcode
Validation URL: URL to validate transactions
Confirmation URL: URL to receive transaction confirmations
Environment: Sandbox or Production

Methods

setValidationUrl(string $url)

Sets the validation URL for transaction validation.

$mpesa->setValidationUrl("https://your-domain.com/validate");

setConfirmationUrl(string $url)

Sets the confirmation URL for transaction confirmations.

$mpesa->setConfirmationUrl("https://your-domain.com/confirm");

register()

Registers the C2B URLs with M-Pesa.

$result = $mpesa->register();

setPhoneNumber(string $phone)

Sets the customer's phone number for simulation.

$mpesa->setPhoneNumber("254712345678");

setAmount(float $amount)

Sets the transaction amount for simulation.

$mpesa->setAmount(100.00);

setBillReference(string $reference)

Sets the bill reference for simulation.

$mpesa->setBillReference("Bill123");

setBillReferenceNumber(string $number)

Sets the bill reference number for simulation.

$mpesa->setBillReferenceNumber("REF123");

simulate()

Simulates a C2B payment.

$result = $mpesa->simulate();

Response Handling

Registration Response

The registration response includes:

ResponseCode: Response code from M-Pesa
ResponseDescription: Description of the response
OriginatorConversationID: Original conversation ID
ConversationID: Unique identifier for the conversation

if ($result->isSuccessful()) {
    echo "Registration successful";
    echo "Conversation ID: " . $result->getConversationID();
} else {
    echo "Error: " . $result->getErrorMessage();
}

Simulation Response

The simulation response includes:

ResponseCode: Response code from M-Pesa
ResponseDescription: Description of the response
CustomerMessage: Message to display to the customer
MerchantRequestID: Unique identifier for the merchant request

if ($simulation->isSuccessful()) {
    echo "Simulation successful";
    echo "Customer Message: " . $simulation->getCustomerMessage();
} else {
    echo "Error: " . $simulation->getErrorMessage();
}

Validation Endpoint

Create an endpoint to handle validation requests:

// validate.php
$validationData = json_decode(file_get_contents('php://input'), true);
 
// Validate the transaction
$valid = validateTransaction($validationData);
 
// Send response
header('Content-Type: application/json');
echo json_encode([
    'ResultCode' => $valid ? 0 : 1,
    'ResultDesc' => $valid ? 'Success' : 'Failed'
]);

Confirmation Endpoint

Create an endpoint to handle confirmation requests:

// confirm.php
$confirmationData = json_decode(file_get_contents('php://input'), true);
 
// Process the confirmation
processConfirmation($confirmationData);
 
// Send response
header('Content-Type: application/json');
echo json_encode([
    'ResultCode' => 0,
    'ResultDesc' => 'Success'
]);

Best Practices

Error Handling
- Implement comprehensive error handling
- Log all transactions
- Monitor failed transactions
Validation
- Validate all incoming requests
- Implement proper security measures
- Check transaction amounts
Security
- Use HTTPS for all URLs
- Validate phone numbers
- Implement proper authentication
- Secure sensitive data
Testing
- Test in sandbox environment first
- Use test phone numbers
- Verify callback handling
- Test with various amounts