Quickstart

Sign in to the AgentPay console and open Developer, API keys. Keys look like mk_live_... and are shown once, at creation. Put it in an environment variable, never in a file you commit.

export AGENTPAY_API_KEY="mk_live_your_key_here"

Every example in these docs runs against the live API at https://api.joomjoo.com with the bearer header. The SDKs wrap the same calls.

# nothing to install
curl https://api.joomjoo.com/v1/wallet \
  -H "Authorization: Bearer $AGENTPAY_API_KEY"

npm install @agentpay-global/sdk

pip install agentpay-global

A new account gets a small signup gift on its first card. For anything else, add money in the console under Balance, or ask the API for a Stripe top-up page and open it for the person.

curl https://api.joomjoo.com/v1/wallet/funding-sessions \
  -H "Authorization: Bearer $AGENTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50}'

The wallet is credited the moment Stripe confirms. Read it back with GET /v1/wallet: available is what a new card can be capped at.

A single-use card capped at 20 dollars for one merchant. The response is a real card.

curl https://api.joomjoo.com/v1/cards \
  -H "Authorization: Bearer $AGENTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 20, "merchant": "namecheap", "single_use": true}'

import { AgentPay } from "@agentpay-global/sdk";

const agentpay = new AgentPay(process.env.AGENTPAY_API_KEY);
const card = await agentpay.cards.create({ amount: 20, merchant: "namecheap", single_use: true });
console.log(card.last4, card.spend_request_id);

import os
from agentpay import AgentPay

agentpay = AgentPay(api_key=os.environ["AGENTPAY_API_KEY"])
card = agentpay.cards.create(amount=20, merchant="namecheap", single_use=True)
print(card["last4"], card["spend_request_id"])

{
  "id": "card_8f2a...",
  "brand": "visa",
  "last4": "8339",
  "exp_month": 4,
  "exp_year": 2033,
  "spend_limit": 20,
  "single_use": true,
  "status": "ACTIVE",
  "spend_request_id": "spr_1c9d...",
  "request_id": "req_a1b2c3"
}

Reveal the number only at the moment of use with GET /v1/cards/{id}, and check whether it was charged with GET /v1/spend/{spend_request_id}.

Skip cards entirely. Give a task, a merchant and a cap. AgentPay opens the site in its own browser, reaches the review, mints the card for the real total, pays, and clears 3DS. It is asynchronous: you get a checkout_id and poll it.

curl https://api.joomjoo.com/v1/checkout \
  -H "Authorization: Bearer $AGENTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "buy the domain example.click for 1 year", "merchant": "namecheap", "amount": 20, "confirm_pay": false, "idempotency_key": "order-001"}'

const run = await agentpay.checkout.create({
  task: "buy the domain example.click for 1 year",
  merchant: "namecheap",
  amount: 20,
  confirm_pay: false,
  idempotency_key: "order-001",
});
let status = await agentpay.checkout.get(run.checkout_id);

run = agentpay.checkout.create(
    task="buy the domain example.click for 1 year",
    merchant="namecheap",
    amount=20,
    confirm_pay=False,
    idempotency_key="order-001",
)
status = agentpay.checkout.get(run["checkout_id"])

With confirm_pay: false the run stops at the final review and waits for the account owner's yes in the console. With confirm_pay: true it pays on its own, up to the cap. Poll GET /v1/checkout/{id} until status is submitted, canceled, blocked or error.