​
OpenAI Integration

This guide demonstrates how to integrate PayLink with OpenAI’s models to create AI assistants that can process payments. The integration uses PayLink’s OpenAI adapter, which formats PayLink tools to be compatible with OpenAI’s function calling API.

​
Prerequisites

Before you begin, make sure you have:
  • Installed the PayLink SDK
  • An OpenAI API key
  • Access to a PayLink server with payment tools

​
Installation

Install the required packages: 
pip install paylink-sdk openai

​
Basic Integration

First, initialize the PayLink client using the OpenAI adapter: 
from paylink_sdk.openai_adapter.toolkit import PayLinkClient

# Initialize the client
paylink_client = PayLinkClient()

# List available tools in OpenAI-compatible format
tools = await paylink_client.list_tools()
The PayLinkClient from the openai_adapter.toolkit module automatically formats PayLink tools in a way that’s compatible with OpenAI’s function calling API.

​
Step 2: Set Up OpenAI Client

Initialize the OpenAI client: 
from openai import OpenAI

client = OpenAI(api_key="OPENAI_API_KEY")

​
Step 3: Create a Conversation with Tool Calls

Send a user message to OpenAI with the PayLink tools: 
input_message = [
    {
        "role": "user",
        "content": "Initiate an stk push to 2547123456789 amount is 1ksh account reference invoice, transaction description invoice-123, transaction type CustomerBuyGoodsOnline"
    }
]

# Get response with tool calls
response = client.responses.create(
    model="gpt-4o-mini",
    input=input_message,
    tools=tools
)

# View the response
print(response.output)
The OpenAI model will analyze the user’s request and generate a tool call to the appropriate PayLink function. Once you have the tool call from OpenAI, you can execute it using the PayLink client: 
tool_args = {
    "phone_number": "2547123456789",
    "amount": 1,
    "account_reference": "invoice",
    "transaction_desc": "invoice-123",
    "transaction_type": "CustomerBuyGoodsOnline",
}

result = await paylink_client.call_tool("stk_push", tool_args)

# View the result
print(result)

​
Error Handling

When integrating with payment systems, proper error handling is essential. Here’s how to handle errors: 
try:
    result = await paylink_client.call_tool("stk_push", tool_args)
    # Process successful payment
except Exception as e:
    # Handle payment failure
    error_message = str(e)
    print(f"Payment failed: {error_message}")
    
    # Inform the user about the failure
    messages.append({
        "role": "system",
        "content": f"The payment could not be processed: {error_message}"
    })

​
Tips for Effective Integration

  1. System Instructions: Include clear instructions in your system message about payment capabilities.
  2. Validation: Although OpenAI models can extract payment details, add validation before processing: 
    # Validate phone number format
if not phone_number.startswith("254") or len(phone_number) != 12:
    raise ValueError("Invalid phone number format. Must be 12 digits starting with 254")
    
# Validate amount
if amount <= 0:
    raise ValueError("Amount must be greater than 0")
  3. User Confirmation: For better user experience, confirm payment details before processing: 
    confirmation_message = f"I'll process a payment of {amount} KES from phone number {phone_number}. Is this correct?"
  4. Status Updates: Keep the user informed about the payment status: 
    # Check payment status
status = await paylink_client.call_tool("stk_push_status", {
    "checkout_request_id": result["CheckoutRequestID"]
})

​
Next Steps

Now that you’ve integrated PayLink with OpenAI, you can:
  • Explore other PayLink tools like checking payment status or refunds
  • Enhance your assistant with more complex payment workflows
  • Implement user authentication and authorization
Check out our LangChain integration guide for an alternative approach to AI-powered payments.

​
Troubleshooting

Tool Not Found Error: If you receive a “Tool not found” error, ensure that:
  • The PayLink server is running and accessible
  • You’re using the correct tool name (case-sensitive)
  • Your PayLink SDK is up to date
Payment Failed Error: If the payment fails, check:
  • The phone number is in the correct format (e.g., 254XXXXXXXXX)
  • The amount is within acceptable limits
  • The PayLink server can connect to the payment provider
For more assistance, refer to our troubleshooting guide or contact support.