Authoryze

Check the current status of a purchase request. Read-only: it never issues, draws, or reveals a card. Returns the status (and the denial reason when denied). When approved, it reports a retrievable boolean: true means the single-use card has not been drawn yet, so call retrieve_card ONCE when you are ready to pay; false means the card was already retrieved and cannot be shown again (start a new purchase if you need another). While pending_review it returns review_url, the page where a human approves or denies — relay that link to the person if they ask where the request is. Safe to poll while a request is pending_review or processing.

Get current spending vs. configured limits. Per-agent fields (daily_spent, weekly_spent, monthly_spent, total_budget_spent) reflect rules set on this agent. The optional user_aggregate object reports the owner's cross-agent caps — these apply across every agent on the account and will deny a purchase even if this agent's per-agent rules are not exceeded. The optional team object appears only when this agent belongs to a team: team.monthly is a ceiling across every agent in that team (so it can already be near its limit even if this agent has spent nothing) and team.auto_approve_threshold, when present, overrides this agent's own threshold for deciding what needs human approval. Only configured limits appear in the response.

Report the result of a checkout attempt made with a card from retrieve_card. Call this after EVERY checkout attempt, once you know the result: outcome completed if the merchant took the payment, or not_completed if it was declined or didn't go through, with message saying what happened (for a decline, the merchant's exact decline text). Only the agent that made the request can report on it, and only after retrieve_card drew the card. A not_completed purchase stays in the purchase history, labeled not completed with your message. Your report alone does NOT change any spending total or cap: the purchase keeps counting until it's verified as not charged. For a Privacy.com card that happens automatically when the card is closed and its transactions show no authorization that wasn't declined; for any other card, the account owner or a team admin has to confirm it in the dashboard. Reporting never gives back automatic-spending envelope room: the drawn card can't be revoked, so that room stays used. A Privacy.com card is closed as soon as you report not_completed, so report only once you're done trying with it; if a retry with the same card goes through first, report completed. A purchase reported completed can't be changed to not_completed. Reporting the same outcome again is harmless.

Submit a purchase request. Returns approved, pending_review, denied (with reason), or failed (a recoverable error, safe to retry, though some failures such as a missing Privacy.com key need the account owner to fix a setting first). A request that looks like a duplicate of another recent purchase on the account (same merchant and amount) is NOT auto-approved — it is escalated to pending_review for the account owner to approve, so poll check_status rather than retrying. IMPORTANT for retries: pass a stable idempotency_key that identifies this one distinct purchase intent, and reuse the SAME key if you retry after a timeout or error. Retries with the same key never issue a second card or charge a second fee — they return the original request's result. Use a fresh key only for a genuinely new, separate purchase. After every checkout attempt with a card from retrieve_card, call report_purchase_outcome with the result, whether it went through or not.

Draw and return the single-use virtual card for an APPROVED purchase request. Call this exactly ONCE, only when you are ready to pay. The card details (number, expiry, CVC) are returned inline and shown a SINGLE time — store them immediately and complete the purchase. Drawing is final and happens once (the card can't be drawn again or handed back), so do NOT call this speculatively, to poll status (use check_status for that), or more than once. There is no re-draw: a second call returns already_retrieved. If the request is not yet approved, call check_status and wait until it is. The response also returns cardholder_name and billing_address (line1, line2, city, state, postal_code, country_code). Use them verbatim for the BILLING section of checkout: they are what the card issuer has on file, and the merchant's address check (AVS) compares against them, so substituting anything else will get the purchase declined. Any field the account owner has not filled in is null; if the merchant requires a field that came back null, say so rather than inventing a value. These are NOT a shipping address. If checkout needs somewhere to deliver to, ask the user for a shipping address separately and never reuse the billing address for it unless the user tells you they are the same. After you attempt checkout with this card, ALWAYS call report_purchase_outcome with this request_id: outcome completed if the merchant took the payment, or not_completed with the merchant's message if it was declined or didn't go through.