Save a payment method

One owner handoff

An agent can request a saved card without handling card numbers, creating an email account or collecting owner credentials. This is optional preparation for future payment workflows. Automatic refills and agent-initiated saved-card charges are not available yet. Existing balance top-ups still use an owner-approved checkout.

Use a live key with campaigns:write and send an empty JSON object:

POST /api/v1/billing/setups
Authorization: Bearer $MR_API_KEY
Idempotency-Key: save-card-001
Content-Type: application/json

{}

Give owner_url to the owner. They sign in to the same workspace, consent to saving a card, and follow secure checkout. The agent receives no hosted setup URL, payment token, member identifier, raw card data or charging permission. Saving a card is independent of adding funds and approving advertising. No funds are collected by these endpoints.

Read the result

GET /api/v1/billing/setups/{id} requires campaigns:read. States are awaiting_owner, creating, checkout_ready, outcome_unknown, saved, revoked and expired. Only saved means the provider confirmed a usable card and its billing member for this exact approved checkout. The public response includes the card brand and last four when known, automatic_refills_enabled:false and charge_authority:none. GET never contacts the provider or mutates payment state.

Poll no faster than retry_after_seconds, pause polling when the owner is not interacting, and stop on a terminal state. A setup request expires after 23 hours; expires_at applies to the request, not the card's expiry date. Saved references remain until removed. List requests through GET /api/v1/billing/setups; follow next_cursor in descending UUID order, up to 50 records per page.

The signed callback and background reconciliation normally update the result. If confirmation is delayed, POST /api/v1/billing/setups/{id}/reconcile with {} and campaigns:read. Each call reads one provider page of up to 25 successful intents, retaining its scan position. Retry at the advertised interval until found; this does not create another checkout or charge.

The owner return page can supply {"setup_intent_id":"sint_..."} as a lookup hint. A redirect, URL query, screenshot or success flag never proves that a card was saved. The server retrieves the intent and checks its account, checkout, owner metadata, versioned consent, payment method and billing member before recording success.

Retries and cancellation

Keep the same Idempotency-Key after a request timeout. Creation replay returns the original request, including after cancellation or expiry. A different request while one is pending returns payment_setup_pending with details.setup_id; continue that ID. There are at most ten new requests per workspace per 24 hours. Sandbox keys cannot access real setup.

Only the signed-in owner can POST /api/v1/billing/setups/{id}/approve with {"consent":true}. Concurrent requests use one stored provider operation. outcome_unknown means retry the same approval after five seconds; do not create a new request. Provider account changes or missing member permissions require operator review.

Only the owner can DELETE /api/v1/billing/setups/{id}. This revokes the workspace reference and is safe to repeat. Late callbacks cannot restore a revoked or expired request. Removal does not delete the owner's card from the payment provider's account or other products. Owners can manage this under Dashboard → Balance → Payment methods.

Spending remains separate

Neither a saved card nor this consent authorizes an automatic debit. A future refill feature must obtain a separate owner mandate with a total charge cap, expiry and revocation, include payment costs and taxes, verify each receipt, and retain the campaign's independent spending approval. Do not promise automatic funding from this setup status.