Introduction

The BCN Payments API enables developers to build powerful digital commerce experiences by embedding secure M-Pesa, card, and bank payment flows into web or mobile applications. The API is RESTful and returns JSON-formatted responses, making it easy to integrate across any modern development stack.

All requests are made via HTTPS and require proper authentication headers. You can test your integrations in Sandbox Mode before going live.

Base URL

All endpoints are served under the following base URL:

https://api.bcnnetworks.co.ke/payments

The API supports both POST and GET methods, depending on the resource being accessed.

Authentication

Authentication is handled via a Bearer Token (API Key). This key identifies your business and must be passed in every request header.

Authorization: Bearer YOUR_API_KEY

To obtain your key, log in to your BCN Developer Dashboard and navigate to the “API Keys” tab.

• Keep your API key secret — never expose it in client-side code.
• Use different keys for Sandbox and Live environments.
• All keys are tied to your verified BCN Business Account.

POST /generate-link

Creates a secure payment link for your customer to complete a transaction.

Request Example

{
  "business_name": "Tech Pesa Ltd",
  "amount": 1500,
  "currency": "KES",
  "callback_url": "https://yourapp.com/payment/callback",
  "description": "Service Payment"
}

Response Example

{
  "status": "success",
  "message": "Payment link generated successfully",
  "data": {
    "link_id": "LN983764",
    "payment_url": "https://bcnnetworks.co.ke/pay/LN983764"
  }
}

Use case: Perfect for small businesses or apps collecting payments per order or subscription.

GET /transaction-status/{id}

Fetches the current state of a payment using its transaction ID. The status can be pending, successful, or failed.

GET https://api.bcnnetworks.co.ke/payments/transaction-status/LN983764

Response

{
  "status": "success",
  "transaction": {
    "id": "LN983764",
    "amount": 1500,
    "currency": "KES",
    "method": "M-Pesa",
    "status": "successful",
    "timestamp": "2025-11-04T11:30:00Z"
  }
}

POST /settlements

Initiates a withdrawal (settlement) to a registered till, Paybill, or bank account.

Request Example

{
  "amount": 5000,
  "destination": "Till",
  "account": "567234",
  "reference": "Weekly Settlement"
}

Response Example

{
  "status": "processing",
  "message": "Your settlement request has been initiated",
  "settlement_id": "ST45682"
}

Webhooks

BCN supports webhooks for asynchronous payment updates. Once a transaction is completed, BCN sends a POST request to your specified callback_url.

Example Payload

{
  "transaction_id": "LN983764",
  "status": "successful",
  "amount": 1500,
  "currency": "KES",
  "timestamp": "2025-11-04T11:32:00Z"
}

Ensure your endpoint returns a 200 OK response to confirm receipt.

Error Handling

Errors are returned in JSON format with descriptive messages and standard HTTP status codes:

Example Error

{
  "status": "error",
  "message": "Invalid API key or missing authorization header",
  "code": 401
}

• 400 – Bad Request (missing or invalid parameters)
• 401 – Unauthorized (invalid API key)
• 404 – Resource not found
• 500 – Internal server error

Sandbox Environment

The Sandbox environment allows you to simulate transactions without using real money. Use it to test integrations safely.

Sandbox Base URL: https://sandbox.bcnnetworks.co.ke/payments

Switch to production when ready to go live. Sandbox transactions will always return simulated data and do not reach payment processors.

SDKs & Libraries

BCN provides SDKs and example code for major languages and frameworks:

• Node.js SDK – npm install bcn-payments
• PHP SDK – composer require bcn/payments
• React Hooks – prebuilt payment components
• WordPress Plugin – Easy integration for WooCommerce

Developer Support

If you encounter issues, reach out to the BCN Developer Support Team:

📧 Email: support@bcnnetworks.co.ke

📘 Documentation Portal: developers.bcnnetworks.co.ke

💬 Live Chat: Available on your BCN Dashboard under Developer → Help