Request a purchase
request_purchaseSubmit 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Purchase amount in the specified currency | |
| currency | No | ISO 4217 currency code, defaults to USD | |
| description | Yes | What is being purchased | |
| merchant_url | Yes | The merchant's full URL, including https:// (e.g. https://amazon.com, https://aws.amazon.com). Required. A bare domain such as amazon.com is still accepted and treated as https://amazon.com. Its hostname is used for whitelist/blacklist matching with subdomain support, so 'amazon.com' on the whitelist allows https://aws.amazon.com. | |
| category_hint | No | Merchant category slug (e.g. cloud_compute, software_saas) | |
| justification | Yes | Why this purchase is needed. Required for all requests | |
| merchant_name | No | Optional human-readable merchant name (e.g. 'AWS', 'GitHub') | |
| idempotency_key | No | Stable key for this one purchase intent. Reuse the SAME key when retrying so retries don't double-charge or double-issue a card (the server dedups on it atomically). Generate a fresh key only for a genuinely new purchase. Independent of the key, the server also runs a best-effort near-duplicate check on (merchant, amount) across the whole account and escalates suspected duplicates to pending_review for the account owner to decide; passing a stable key is still strongly recommended because it is the only fully atomic protection against concurrent double-submits. | |
| merchant_country_code | Yes | ISO 3166-1 alpha-2 country code of the MERCHANT (the store being purchased from, not the user's country). Required. Examples: 'US', 'GB', 'DE', 'CA', 'AU'. |