joomjoo

The official Joomjoo 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 joomjoo

Requires Python 3.8+.

Quickstart

import os
from joomjoo import Joomjoo

joomjoo = Joomjoo(api_key=os.environ["JOOMJOO_API_KEY"])  # key looks like mk_live_...

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

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

Tools

Cards

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

Spend status

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

Checkout (Joomjoo drives the buy)

run = joomjoo.checkout.create(
    task="buy the domain joomjoo.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 = joomjoo.checkout.get(run["checkout_id"])
# status["status"]: "queued" | "running" | "awaiting_approval" | "needs_login" | "submitted" | "blocked"

Connections (login-gated merchants)

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

Errors

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

from joomjoo import Joomjoo, JoomjooError

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

Configuration

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

Docs

The wallet

w = joomjoo.wallet.get()                                        # balance, available, reserved, pending, in dollars
s = joomjoo.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 = joomjoo.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.joomjoo.com (Developer, Docs)