agentpay

The official AgentPay SDK for Python. Issue capped virtual cards and let your agent complete real checkouts. Card controls, 3DS, and fraud caps are handled for you. Zero dependencies.

Install

pip install agentpay-global

Requires Python 3.8+.

Quickstart

import os
from agentpay import AgentPay

agentpay = AgentPay(api_key=os.environ["AGENTPAY_API_KEY"])  # key looks like mk_live_...

# Issue a single-use card capped at $20
card = agentpay.cards.create(amount=20, merchant="namecheap", single_use=True)
print(card["id"], card["last4"], card["spend_limit"])

Get your API key from the AgentPay console (Developer -> API keys). Keep it server-side; never commit it.

Tools

Cards

card = agentpay.cards.create(amount=20, merchant="namecheap", single_use=True)
full = agentpay.cards.reveal(card["id"])   # {"number","cvc","exp",...}: use at the moment of purchase
closed = agentpay.cards.close(card["id"])  # release the unused reserve back to your wallet

Spend status

spend = agentpay.spend.get(card["spend_request_id"])
# spend["status"]: "not_started" | "authorized" | "cleared" | "declined"

Checkout (AgentPay drives the buy)

run = agentpay.checkout.create(
    task="buy the domain example.click for 1 year",
    merchant="namecheap",
    amount=20,
    confirm_pay=False,  # dry run: stops at the final review. True = pay up to the cap.
)

status = agentpay.checkout.get(run["checkout_id"])
# status["status"]: "queued" | "running" | "awaiting_approval" | "needs_login" | "submitted" | "blocked"

Connections (login-gated merchants)

conn = agentpay.connections.create(merchant="namecheap", user_ref="user-123")
# open conn["connect_url"] so the user signs in, then:
agentpay.connections.complete(conn["connection_id"])
# now pass connection_id to checkout.create to run signed-in

Errors

Any non-2xx response raises AgentPayError with the HTTP status, the AgentPay error code, and the request id.

from agentpay import AgentPay, AgentPayError

try:
    agentpay.cards.create(amount=999999, merchant="namecheap")
except AgentPayError as e:
    print(e.status, e.code, e.request_id)  # e.g. 402 insufficient_funds

Configuration

AgentPay(
    api_key=os.environ["AGENTPAY_API_KEY"],
    base_url="https://api.joomjoo.com",  # optional override
    timeout=60.0,
)

Docs

The wallet

w = agentpay.wallet.get()                                        # balance, available, reserved, pending, in dollars
s = agentpay.wallet.create_funding_session(amount=50, success_url="https://yourapp.example/funded")
# open s["url"] for the person; the wallet is credited when Stripe confirms (webhook event money.funded)
t = agentpay.wallet.declare_bank_transfer(amount=500, rail="wire_domestic")
# t["instructions"] holds the account to send to and t["reference_code"] goes in the memo

Full API reference: https://app.agentpay.global (Developer, Docs)