Skip to main content
After configuring your environment, test your M-Pesa payment provider connection to ensure everything is set up correctly.
1

Initialize PayLink client

Import and initialize the PayLink client:
from paylink import PayLink

client = PayLink()
2

List available tools

List all available tools to verify your connection:
list_tools = client.list_tools()
print(list_tools)
Example response:
[Tool(name='stk_push', title=None, description="Initiates M-Pesa Express (STK Push) payment on behalf of a customer. Sends a payment prompt to the customer's phone requesting them to enter their M-Pesa PIN to authorize and complete payment.", inputSchema={'type': 'object', 'properties': {'amount': {'type': 'string', 'description': 'Amount to be transacted (only whole numbers supported).', 'pattern': '^[0-9]+$'}, 'phone_number': {'type': 'string', 'description': "Customer's M-Pesa registered phone number to receive the payment prompt (format: 2547XXXXXXXX).", 'pattern': '^2547[0-9]{8}$'}, 'account_reference': {'type': 'string', 'description': 'Reference identifier for the transaction (max 12 characters). This will be displayed to the customer in the payment prompt.', 'maxLength': 12}, 'transaction_desc': {'type': 'string', 'description': 'Description of what the payment is for (max 13 characters).', 'maxLength': 13}}, 'required': ['amount', 'phone_number', 'account_reference', 'transaction_desc']}, outputSchema=None, icons=None, annotations=None, meta=None)]
​
name
string
required
The unique identifier for the tool (e.g., "stk_push").
​
title
string | None
Optional display title for the tool.
​
description
string
A human-readable description of what the tool does.
​
inputSchema
dict
required
JSON schema defining the required and optional parameters for the tool. Contains type, properties, and required fields.
​
outputSchema
dict | None
JSON schema defining the expected output format of the tool.
​
icons
list | None
Optional list of icon identifiers for the tool.
​
annotations
list | None
Optional list of annotations or metadata associated with the tool.
​
meta
dict | None
Additional metadata about the tool.
3

Invoke a tool

The tool name is mpesa. The tool requires the following parameters:
tool_name = "mpesa"

params = {
    "amount": "1",
    "phone_number": "your phone number",
    "account_reference": "test",
    "transaction_desc": "test"
}
Now call the tool:
response = client.call_tool(
    tool_name,
    params
)
print(response)
Example response:
meta=None content=[TextContent(type='text', text='{\n  "status": "success",\n  "message": "Success. Request accepted for processing",\n  "merchant_request_id": "fe0e-47f1-8ce8-2f3d326b82df19963",\n  "checkout_request_id": "ws_CO_30112025102557814797357665",\n  "amount": "1",\n  "phone_number": "254797357665",\n  "reference": "test"\n}', annotations=None, meta=None)] structuredContent=None isError=False
​
meta
dict | None
Optional metadata associated with the response.
​
content
list
required
List of content blocks returned by the tool. Each block contains the response data, typically as TextContent objects with the tool’s output.
​
structuredContent
dict | None
Optional structured representation of the response content.
​
isError
boolean
required
Indicates whether the tool invocation resulted in an error. False means the call was successful.

​
Expected Results

If your configuration is correct, you should see:
  • ✓ Tools listed successfully (including stk_push)
  • ✓ Tool invocation returns a success response with checkout_request_id
  • ✓ Payment prompt sent to the specified phone number
If you encounter errors, verify:
  • Your PAYLINK_API_KEY is valid and active
  • Your PAYLINK_PROJECT matches the project name in your dashboard
  • Your M-Pesa Daraja credentials are correct
  • Your MPESA_BASE_URL points to the correct environment (sandbox or production)
Use sandbox credentials while testing to avoid live charges.

​
Next Steps

Now that your payment provider is working correctly, you’re ready to build your agent. Proceed to Build Agent to integrate PayLink into your AI agent workflow.