pinelabs-agent-toolkit (Python)

Pine Labs payment APIs as tools for AI agent frameworks — OpenAI (Chat Completions + Agents SDK), LangChain, Pydantic AI, CrewAI, and Anthropic Claude. Built on top of pinelabs-python.

74 Pine Labs operations (orders, refunds, payouts, payment links, settlements, subscriptions, …) become typed, schema-validated tools your agent can call.

The npm equivalent is pinelabs-agent-toolkit. Both packages are generated from the same OpenAPI spec and use the same operation names.

Install

pip install pinelabs-agent-toolkit

Then install only the framework adapter(s) you need:

Framework	Extra	Peer dependency
OpenAI Chat Completions + Agents SDK	[openai]	openai, openai-agents
LangChain	[langchain]	langchain-core
Pydantic AI	[pydantic-ai]	pydantic-ai
CrewAI	[crewai]	crewai
Anthropic Messages API	[anthropic]	anthropic
Everything	[all]	all of the above

pip install 'pinelabs-agent-toolkit[openai,langchain]'

Requires Python ≥ 3.9.

Authenticate

The toolkit takes your Pine Labs OAuth credentials and handles client_credentials token refresh automatically (with a thread-safe cache and a separate bootstrap auth client so the supplier callback can never recurse):

from pinelabs_agent_toolkit.shared import pinelabs_environment

opts = dict(
    environment=pinelabs_environment["UAT"],  # or pinelabs_environment["PROD"]
    client_id="<client-id>",
    client_secret="<client-secret>",
)

Constant	Base URL
pinelabs_environment["UAT"]	https://pluraluat.v2.pinepg.in
pinelabs_environment["PROD"]	https://api.pluralpay.in

Or pass any URL string directly to environment.

Never commit your client_id / client_secret. Load them from environment variables or a secret manager.

Quickstart by framework

OpenAI Chat Completions

import json
import openai
from pinelabs_agent_toolkit.openai import PinelabsAgentToolkit
from pinelabs_agent_toolkit.shared import pinelabs_environment

toolkit = PinelabsAgentToolkit(
    environment=pinelabs_environment["UAT"],
    client_id="<client-id>",
    client_secret="<client-secret>",
)

client = openai.OpenAI()
messages = [{"role": "user", "content": "Create a 500 INR order with reference ord-1."}]

while True:
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=toolkit.get_tools(),
    )
    msg = resp.choices[0].message
    messages.append(msg)
    if not msg.tool_calls:
        break
    for call in msg.tool_calls:
        out = toolkit.handle_tool_call(call.function.name, call.function.arguments)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": out})

OpenAI Agents SDK

from agents import Agent, Runner
from pinelabs_agent_toolkit.openai import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

agent = Agent(
    name="Payments Agent",
    instructions="Help the user manage Pine Labs payments.",
    model="gpt-4o",
    tools=toolkit.get_agent_tools(),
)
result = Runner.run_sync(agent, "Create a 500 INR order for ord-1.")
print(result.final_output)

LangChain

from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from pinelabs_agent_toolkit.langchain import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, toolkit.get_tools())
result = agent.invoke({"messages": [("user", "Create a 500 INR order.")]})

Pydantic AI

from pydantic_ai import Agent
from pinelabs_agent_toolkit.pydantic_ai import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

agent = Agent("openai:gpt-4o", tools=toolkit.get_tools())
result = agent.run_sync("Create a 500 INR order with reference ord-1.")
print(result.output)

CrewAI

from crewai import Agent, Crew, Task
from pinelabs_agent_toolkit.crewai import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

payments = Agent(
    role="Payments Specialist",
    goal="Manage Pine Labs payment links and orders.",
    backstory="You are an expert at the Pine Labs payment APIs.",
    tools=toolkit.get_tools(),
)

task = Task(
    description="Create a payment link for 500 INR.",
    expected_output="The payment link URL.",
    agent=payments,
)
Crew(agents=[payments], tasks=[task]).kickoff()

Anthropic Claude (Messages API)

import anthropic
from pinelabs_agent_toolkit.anthropic import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Create a 500 INR order."}]

while True:
    resp = client.messages.create(
        model="claude-3-5-sonnet-latest",
        max_tokens=1024,
        tools=toolkit.get_tools(),
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})
    tool_uses = [b for b in resp.content if b.type == "tool_use"]
    if not tool_uses:
        break
    results = [
        {
            "type": "tool_result",
            "tool_use_id": b.id,
            "content": toolkit.handle_tool_use(b.name, b.input),
        }
        for b in tool_uses
    ]
    messages.append({"role": "user", "content": results})

Available tools

The toolkit exposes 74 operations spanning every Pine Labs Online product:

• Authentication — generate access tokens
• Orders — create, capture, fetch, cancel
• Refunds — create, fetch
• Payment Links — create, fetch, cancel, resend, list
• Card / UPI / NetBanking / Wallet — direct payment methods
• Apple Pay / International Payments — alternate rails
• Pay by Points / E-Challans / Affordability Suite / BNPL / Convenience Fee
• Customers / Tokenization — vault and customer management
• Payouts — create, update, cancel, list
• Settlements / Split Settlements — settlement search and reconciliation
• Subscriptions — plans, subscriptions, presentations, debits, retries

Inspect the full list:

from pinelabs_agent_toolkit import ALL_TOOLS

for td in ALL_TOOLS:
    print(td.name, td.method, td.path)

Each tool's input schema is a strict pydantic model — extra fields raise a validation error so the LLM cannot smuggle arbitrary data into the SDK.

Direct SDK access

The toolkit's Pinelabs client is a drop-in replacement for pinelabs.PinelabsApi with token refresh built in. Use it directly when you want to call the SDK outside an agent loop:

from pinelabs_agent_toolkit.shared import Pinelabs

client = Pinelabs(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)
client.orders.get_order_by_id(order_id="ord_123")

Environments

Environment	Base URL
UAT	https://pluraluat.v2.pinepg.in
Production	https://api.pluralpay.in

Versioning

Pre-1.0; expect occasional small breaking changes between minor versions. Operation names and signatures stay in lock-step with the npm pinelabs-agent-toolkit.

License

MIT