Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceBilling and usageBilling

Settle a saved card

Called right after stripe.confirmSetup succeeds. Settles the card the SetupIntent saved and reports whether it was saved, refused, or held. Settlement runs once: a card tied to fraud, or a second card the bank did not verify when it was asked to, puts the account on hold (held, ACCOUNT_PENDING_VERIFICATION); a card the bank did not verify is removed (refused, CARD_NOT_VERIFIED); any other card becomes the account's default (saved). Calling it again, or after the Stripe webhook settled the card, answers the same outcome and changes nothing.

Required permission

Requires the billing.manage permission. See Permissions for the roles and API key permissions that include it.

POST
/v1/orgs/{orgId}/billing/setup-intent/{setupIntentId}/complete

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Path Parameters

orgId*string
setupIntentId*string
Lengthlength <= 255

Response Body

How the card was settled

application/json
  1. response
status*string

saved: the card is the account's default. refused: the card was removed; add a different one. held: the card was removed and the account is on a verification hold.

Value in"saved""refused""held"
code?string

Why the card was not kept. Absent for a saved card.

Value in"CARD_NOT_VERIFIED""ACCOUNT_PENDING_VERIFICATION"
message*string

What to show the customer.

Example Request
curl -X POST 'https://api.openrelay.inc/v1/orgs/string/billing/setup-intent/string/complete'
Example Response
{  "status": "saved",  "code": "CARD_NOT_VERIFIED",  "message": "string"}

Start saving a card (Stripe SetupIntent) POST

Creates a Stripe SetupIntent to save a card and returns its client secret, the publishable key, and bankCheck, true when the bank must confirm the card. The inline Elements form confirms the client secret. The dashboard's card form sends its device identification and a Turnstile token as optional query parameters, and the card save is judged on them: a device that puts the account on a verification hold gets 403 ACCOUNT_PENDING_VERIFICATION, or 403 VERIFICATION_UNAVAILABLE when the hold could not be recorded. Anything else that looks wrong about the request or the account (no verified device, a missing or failed Turnstile token, a new account, a recent failed card, and more) asks the card's bank to confirm the card with 3D Secure, and bankCheck says so. The operation takes no request body, so a bare POST (the CLI, the MCP tool) still works and its card always needs the bank's confirmation. After stripe.confirmSetup succeeds, call the complete operation to learn whether the card was kept.

Charge the saved card to top up prepaid balance POST

Charges the org's default saved card off-session for amountCents and returns the PaymentIntent id and status, which tells the client what to do next. The balance credit is applied by the payment_intent.succeeded webhook (the authoritative money signal), not this response: poll the balance after success.