openupi / gateway

v0.1.0 2026-11-12 12:48 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *

Apache-2.0

Published on Packagist.org on 2026-11-12 13:14 UTC

README

Each SDK has no dependencies, holds your API key and webhook secret (use it on your server only), and passes the same cases in conformance/vectors.json: amounts, the exact request each call sends, and webhook signature checks. make sdk-test runs them all.

Language	Where	Needs
JavaScript (Node)	node/	Node 18+
Python	python/agentgrid_pay.py	Python 3.8+
Go	go/ (github.com/ayushks1ngh/agentgrid-sdk/go)	Go 1.23
Java	java/src/site/agentgrid/sdk/	Java 11+
PHP	php/src/ (Agentgrid\GatewayClient)	PHP 8.1+ with curl and json

The HTTP API itself: /docs and /openapi.json on any Agentgrid PSP.

Install

npm install agentgrid                            # Node 18+
pip install agentgrid-pay                        # Python 3.8+
go get github.com/ayushks1ngh/agentgrid-sdk/go   # Go 1.23+
composer require agentgrid/sdk                   # PHP 8.1+

<dependency>
  <groupId>site.agentgrid</groupId>
  <artifactId>agentgrid-sdk</artifactId>
  <version>0.2.0</version>
</dependency>

Licensed under Apache-2.0 (LICENSE).

Every SDK has the same rules: amounts are rupees with at most two decimals (more is refused, never rounded); the same order id and amount returns the same order, so retrying is safe; a refund needs the shop's PIN; a valid webhook signature proves who sent it, not that money arrived, so confirm with get-order before you ship and deduplicate on deliveryId.

from agentgrid_pay import GatewayClient
gw = GatewayClient("https://pay.example", "gk_test_...", webhook_secret="whsec_...")
order = gw.create_order("ORD-1001", "499.00", note="T-shirt")
# send the customer to order["checkoutUrl"]; in your webhook handler:
event = gw.verify_webhook(request_body_bytes, request_headers)

gw := agentgrid.New("https://pay.example", "gk_test_...")
order, err := gw.CreateOrder(ctx, agentgrid.OrderInput{OrderID: "ORD-1001", Amount: "499.00"})

GatewayClient gw = new GatewayClient("https://pay.example", "gk_test_...", "whsec_...");
Map<String, Object> order = gw.createOrder("ORD-1001", "499.00", "T-shirt");

CLI

sdk/go/cmd/agentgrid signs in with a test key, creates and lists test orders, pays them as a sandbox payer (agentgrid pay <id> --as decline@sandbox), triggers events, and listen --forward http://localhost:3000/webhook sends test webhooks to your laptop, signed as the gateway signs them. It refuses live keys. See docs/GATEWAY.md.

$gw = new Agentgrid\GatewayClient('https://pay.example', 'gk_test_...', 'whsec_...');
$order = $gw->createOrder('ORD-1001', '499.00', 'T-shirt');
$event = $gw->verifyWebhook(file_get_contents('php://input'), getallheaders());

For AI agents

An AI agent pays from the reserve its payer blocked at their own bank; the bank checks every payment. The Node and Python SDKs sign each agent request (Ed25519) and check pay-per-call receipts. The rules an agent works within are at https://agentgrid.site/agentgrid.md.

import { AgentClient, requirePayment } from "agentgrid/agent";

const agent = new AgentClient({ baseUrl: "https://app.example", agentId: "agt_...", key: process.env.AGENT_KEY });
await agent.pay({ to: "shop@bank", amount: "49.00", idempotencyKey: "order-1001" });
const res = await agent.fetchPaying("https://api.example/v1/search?q=chai"); // pays a 402 once, then retries

// An API that charges agents per call:
app.use("/v1/search", requirePayment({ payTo: "api@bank", amount: "0.50", recordKey: PSP_RECORD_KEY }));

from agentgrid_pay import AgentClient   # pip install 'agentgrid-pay[agent]'

agent = AgentClient("https://app.example", "agt_...", key=AGENT_SEED)
agent.pay("shop@bank", "49.00", idempotency_key="order-1001")