Wilby DocsGet Sandbox Keys

API Reference

Built from the server's own request rules, so it matches what the API accepts. Base URL https://dev.usewilby.com.

Download the OpenAPI file (OpenAPI 3.1) to load into Postman, Insomnia or a code generator.

Partner endpoints use Authorization: Bearer oh_… and every POST needs an Idempotency-Key header. Assistant endpoints use the assistant's oha_… key.

StoresOrdersIncremental Charges and TipsCustomer PermissionsOutside Agent PermissionsBank PaymentsPlatform-Run PaymentsDisputesRecordsReportsReady-Made ScreensWebhooksSandboxAgent APIAgent StorefrontAI Agents on Your WebsitePublic

Stores

The businesses you take payments for.

POST/v1/merchants

Add or update a store. Set processor to the store's processor (stripe live; test or test_noholds in the sandbox) and processor_account_ref to its account there.
Body fieldTypeNotes
external_ref requiredstringup to 200 chars; Your own id for it.
name requiredstringup to 200 chars; A name.
processor requiredstringup to 40 chars; The payment processor (stripe, square, braintree, adyen, paypal).
processor_account_ref requiredstringup to 200 chars; The store's account id at its processor.
settingsobjectSettings for this store.

POST/v1/merchants/{ref}/connect-link

Get a link for the store owner to connect their own account. Square: "Connect with Square" (the owner approves on Square). Braintree: the owner enters the store's own API keys, checked with Braintree first. Adyen: the owner enters the store's API key, merchant account and webhook HMAC key, checked with Adyen first. PayPal: the owner enters the client ID and secret of their PayPal app, checked with PayPal first; Wilby adds its webhook to that app. Valid 7 days, used once. Credentials are stored encrypted and never shown again.
ParameterInTypeNotes
ref requiredpathstringYour own id (in the address).
Body fieldTypeNotes
processor requiredsquare braintree adyen paypalThe payment processor (stripe, square, braintree, adyen, paypal).

GET/v1/merchants/{ref}/connections

See which account a store's payments run on (its own, or platform keys)
ParameterInTypeNotes
ref requiredpathstringYour own id (in the address).

POST/v1/merchants/{ref}/disconnect

Disconnect a store's own account. Square access is revoked at Square too. The store goes back to platform keys, if any.
ParameterInTypeNotes
ref requiredpathstringYour own id (in the address).
Body fieldTypeNotes
processor requiredsquare braintree adyen paypalThe payment processor (stripe, square, braintree, adyen, paypal).

POST/v1/settings/stripe-key

Save your own Stripe key (Wilby charges on your Stripe). A restricted key (rk_test_… on sandbox, rk_live_… on live) for your Stripe platform or account. Checked with Stripe, then sealed; never shown again (GET /v1/settings shows its kind and last 4). Stores under your platform use their connected account id as processor_account_ref; a store on your own account uses "self". Without a key, Wilby uses its own Stripe platform.
Body fieldTypeNotes
stripe_key requiredstringup to 300 chars; Your Stripe restricted key (saved, never shown again).

DELETE/v1/settings/stripe-key

Remove your Stripe key

GET/v1/integration/check

What's done and what's left before going live. From your settings and your last 30 days of activity with this key's mode: stores, orders end to end, reporting (if you charge), webhooks, codes, your look, screens and agents (if used), and going live. Each item is done, check or missing, with the fix and a docs link. Read-only. The same list is the Setup tab in Dashboard.

GET/v1/settings

Your settings: extra-charge choices and your look on customer pages

POST/v1/settings

Change your settings. Every setting is explained on the Settings page (/docs/settings). rule_choices_pct (1 to 4 percents; "always ask me first" is always offered), recommended_pct, branding (display name, color, logo, whether the Wilby line shows), and return_url (default "back to your app" address for every customer page), wording (your own lines on customer pages) and apps (your iOS app ids and Android packages with signing-certificate fingerprints, to approve inside your app). agent_access chooses which AI agents may order from you: {"mode": "all", "blocked": ["perplexity"]} or {"mode": "only", "allowed": ["claude", "chatgpt"]}, plus "verified_only": true to require a signed identity. screen_origins: your websites where Wilby's ready-made screens run (up to 10 https origins). first_setup_code (default true): before a customer's first passkey is set up, a one-time code proves it's them (when a code can reach them: your text or Wilby's email). ucp: take Google's agent checkout (UCP): {"enabled": true, "website_url", "terms_url", "require_signatures", "google_pay": {"gateway", "gateway_merchant_id", "merchant_id", "merchant_name"}} (needs the storefront on with the catalog answer; see Agent Storefront).
Body fieldTypeNotes
return_urlstring or nullup to 500 chars; Where Wilby's pages send the customer when they are done (https, or your app's own link).
wordingobjectYour own lines on customer pages (keys like extra_title; null goes back to Wilby's default).
storefrontobjectfields: enabled, slug, name, description, login_url, api_url, answers, extras, times_path; Your Agent Storefront: enabled, slug, name, description, login_url, api_url, answers, extras, times_path.
appsobjectfields: ios, android; Your iOS and Android apps, so customers can approve inside your app.
agent_rulesobject or nullYour own rules for AI agent orders, stricter than the customer's: max_order_cents, always_approval_required_above_cents, hours.
embed_originsarrayYour websites that may show the Dashboard inside your own dashboard (up to 5 https origins).
screen_originsarrayYour websites where Wilby's ready-made screens run (up to 10 https origins).
first_setup_codebooleanBefore a customer's first passkey, a one-time code proves it's them (default true).
variable_amountbooleanWhether your final price can change after checkout (default false).
ucpobjectfields: enabled, require_signatures, share_saved_addresses, prefer_mcp, public_base_url, version, terms_url, website_url, google_pay; Google's agent checkout (UCP): enabled, require_signatures, share_saved_addresses, prefer_mcp, public_base_url, version, terms_url, website_url, google_pay.
listingobjectfields: one_liner, long_description, privacy_url, support, docs_url, example_prompts, reviewer_customer_ref, reviewer_steps; What AI app directories ask for: one_liner, long_description, privacy_url, support, docs_url, example_prompts, reviewer_customer_ref, reviewer_steps.
agent_accessobjectfields: mode, verified_only, allowed, blocked; Which AI agents may order from you: mode all or only, allowed, blocked, verified_only.
website_agentsobjectfields: likely; AI agents on your own website: likely (record_only or ask_customer).
rule_choices_pctarrayThe percent choices offered to customers for extra charges (1 to 4).
recommended_pct5 10 15 20 25 30 40 50The choice shown as recommended.
brandingobjectfields: display_name, accent_color, secondary_color, logo_data_uri, show_secured_by; Your look on customer pages: display_name, accent_color, secondary_color, logo_data_uri, show_secured_by.

GET/v1/agent-access/report

See which AI agents ordered from you and which were turned away. For the last 30 days, per agent (claude, chatgpt, gemini, copilot, perplexity, meta, other): orders, orders with a verified signed identity, how many times your Agent Access Policy turned it away, and whether it is allowed now. Set the gate with agent_access on POST /v1/settings.

Orders

An order: what the customer authorized, enforced on every payment.

POST/v1/orders

Create an order. Records what the customer authorized. amount_cents is the order's price: for a fixed price, the price itself (set max_amount_cents to the same amount); if the final price can change, the estimate, and max_amount_cents is the most that may be charged without asking. display_ref is the order number your customer knows; customer pages show it instead of external_ref. With agent_mandates, the order comes from an outside agent and its signed permission is checked first. An AI agent checking out on your own website: add agent_check_id from POST /v1/agent-checks; Wilby applies your Agent Access Policy, your agent rules and the customer's own limits, records the agent, and when the customer must approve first returns customer_approval.url (until they do, confirming or charging the order is refused with customer_approval_needed).
Body fieldTypeNotes
merchant_external_ref requiredstringup to 200 chars; Your own id for the store.
customer requiredobjectfields: external_ref, payment_method_ref; The customer: external_ref (your id for them), and optionally payment_method_ref and customer_contact.
external_refstringup to 200 chars; Your own id for it.
display_refstringup to 40 chars; Your order number as customers know it (shown on Wilby's pages).
purpose requiredstringup to 500 chars; What the order is for, in plain words.
order_typestringup to 60 chars; Your kind of order (your own word).
pricing_termsobjectYour pricing terms for the order (your own keys), shown to the customer.
currencystringThe currency (USD).
amount_cents requiredintegermin 1; max 10000000000; An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.
max_amount_centsintegermin 0; max 10000000000; The most that may be charged for the order without asking the customer again.
expires_atstringup to 40 chars; When it expires (ISO 8601, UTC).
estimate_basisobjectfields: source, entered_amount_cents; How you worked out the estimate (for example "by weight").
agent_mandatesobjectfields: format, checkout, payment, l1, l2_checkout, l2_payment, l3_checkout, l3_payment, platform_kid, complete_request, signature, timestamp, checkout_session, allowance; Signed permissions an outside agent platform sent with the order (AP2 or Verifiable Intent): checkout, payment and the customer's open permissions.
agent_signatureobjectfields: signature_input, signature, signature_agent, authority, path, method, query, headers; The agent's signed HTTP request (RFC 9421 message signature: method, URL, headers, signature) so Wilby can check which agent sent it.
agent_check_idstringThe id of an agent check (POST /v1/agent-checks) to attach to an order.

GET/v1/orders

List orders. Newest first, each with its summary. Filter by customer_external_ref, merchant_external_ref, stage; limit up to 50; next page: before = the next_before you got.
ParameterInTypeNotes
customer_external_refquerystringYour own id for the customer.
merchant_external_refquerystringYour own id for the store.
stagequerystringWhere the order is: created, confirmed, authorized, captured, cancelled, expired, disputed.
limitqueryintegerHow many to return (paging).
beforequerystringList only items created before this id or time (paging).

GET/v1/authorizations/suggest

Suggest the amount to hold. From this customer's own history at this store. Debit and prepaid cards are held closer to what the customer entered.
ParameterInTypeNotes
merchant_external_ref requiredquerystringYour own id for the store.
customer_external_refquerystringYour own id for the customer.
amount_cents requiredqueryintegerAn amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.
card_fundingquerystring: credit debit prepaidThe card type: credit, debit or prepaid.

GET/v1/orders/{id}

Get an order. summary is screen-ready: status_label and next_step in plain words, money (estimate, up to without asking, paid, held, tip, refunded, final), waiting_extra, and each incremental charge with its title, note, card label and how it was decided. Webhooks carry the same block.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/orders/{id}/confirm

Store confirms the order
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/orders/{id}/authorize

Take the payment. Places a hold for the estimate on cards (a charge where holds aren't possible, a debit for bank accounts). Retries never charge twice.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/orders/{id}/capture

Set the final price. Captures the final amount from the hold and releases the rest, or refunds the difference. Above what was paid: ask for an incremental charge first. Optional measure {"unit": "lb", "value": 24}: what was weighed (goods sold by weight), signed into the record and shown on UCP orders as the settled measure.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
capture_cents requiredintegermin 0; max 10000000000; The final amount captured for the order.
measureobjectfields: unit, value; What was measured for the final price: value and unit (for example 18.4 lb).

POST/v1/orders/{id}/cancel

Cancel the order. Releases any hold and refunds anything taken.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
reasonstringup to 500 chars; Why, as a code or in words. On an incremental charge: the store's reason the customer sees.

POST/v1/orders/{id}/refunds

Refund part or all of a captured order
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
amount_cents requiredintegermin 1; max 10000000000; An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.
reason requiredstringup to 300 chars; Why, as a code or in words. On an incremental charge: the store's reason the customer sees.

POST/v1/orders/{id}/fulfillment

Report a shipment (with tracking) or a delivery. {"type": "shipped", "tracking_number", "tracking_url", "carrier"} (tracking number and an https tracking link are required), then {"type": "delivered"}. Optional line_items for part of the order, description (up to 200 characters). Signed into the order's record. Orders from Google's agent checkout (UCP) pass these to the platform and to Google (Google requires shipped and delivered, with tracking).
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
type requiredshipped deliveredWhat kind it is.
tracking_numberstringup to 100 chars; The shipment's tracking number.
tracking_urlstringup to 500 chars; The tracking page (https).
carrierstringup to 60 chars; The shipping company.
descriptionstringup to 200 chars; Plain text describing it. On an order: what was ordered.
line_itemsarrayThe items, each with a name, quantity and amount.

POST/v1/orders/{id}/confirmations

Ask the customer to confirm statements only they can make. Send 1 to 5 statements in your own words (plain text, up to 200 characters each), for example "I'm 21 or older." You get a url to send the customer; they tick each statement and confirm with Face ID or a texted code. The order then shows them under order.customer_statements (and the statements.confirmed webhook). An AI agent can never confirm these.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
statements requiredarrayStatements only the customer can confirm (for example "I am 21 or older").
valid_hoursintegermin 1; max 168; How many hours the link works.
return_urlstringup to 500 chars; Where Wilby's pages send the customer when they are done (https, or your app's own link).

Incremental Charges and Tips

Charging more after the order: inside the customer's limit it goes through; above it, the customer decides.

POST/v1/orders/{id}/incremental-charges

Charge an incremental charge. Inside the customer's limit it is charged at once; above it, the customer gets a link with the reason and evidence and approves in one tap. Optional: reason_title (your own one-line reason, shown in bold), card_label ("Visa •••• 4242", shown as "Charged To"), return_url (where the page sends the customer after they answer).
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
amount_cents requiredintegermin 1; max 10000000000; An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.
reason requiredover_estimate add_on special_handling damage_fee other extra_parts extra_labor substitution price_changeWhy, as a code or in words. On an incremental charge: the store's reason the customer sees.
notestringup to 500 chars; A note in plain words.
before_workbooleanTrue when the incremental charge is asked before the work is done (the customer sees "before we continue").
approval_window_minutesintegermin 5; max 1440; How long the customer has to answer an incremental charge request (minutes).
reason_titlestringup to 80 chars; A short title for the reason (shown as the heading).
card_labelstringup to 40 chars; How the card is shown to the customer, like "Visa •••• 4242".
return_urlstringup to 500 chars; Where Wilby's pages send the customer when they are done (https, or your app's own link).
agent_mandatesobjectfields: format, checkout, payment, l1, l2_checkout, l2_payment, l3_checkout, l3_payment, platform_kid, complete_request, signature, timestamp, checkout_session, allowance; Signed permissions an outside agent platform sent with the order (AP2 or Verifiable Intent): checkout, payment and the customer's open permissions.
agent_signatureobjectfields: signature_input, signature, signature_agent, authority, path, method, query, headers; The agent's signed HTTP request (RFC 9421 message signature: method, URL, headers, signature) so Wilby can check which agent sent it.
customer_contactobjectfields: label, email; How to reach the customer for a one-time code: label (the name on their passkey) and email. Kept 7 days, never in the signed record.
evidence requiredarrayProof for an incremental charge (photos, notes, files): type, label, file_ref, meta.

POST/v1/orders/{id}/incremental-charges/preview

Check whether an incremental charge would need approval. A dry run for your store screen: decision is inside_limit, needs_approval, request_pending or not_allowed, with room_cents (how much more can still be charged without asking). Nothing is created or recorded.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
amount_cents requiredintegermin 1; max 10000000000; An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.

POST/v1/incremental-charges/{id}/decline

Record a decline made in your own app. For a customer signed in to your app who taps Decline. No Face ID or code is needed (declining charges nothing). Recorded as "declined in the platform's app"; the incremental_charge.declined webhook follows.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
notestringup to 300 chars; A note in plain words.

POST/v1/incremental-charges/{id}/passkey/begin

Approve inside your app or on your website: get the Face ID prompt. Works for your registered apps and, since 0.66.3, for your own websites listed in passkey_websites.in_page (GET /v1/settings): your page shows the prompt itself with navigator.credentials. Returns WebAuthn options for this exact extra (its id and amount are in the challenge). kind is register the first time (create a passkey, finish, then begin again) or authenticate. Your app passes options to the phone's passkey sheet. Needs your apps in settings (apps). Since 0.67.0, send the customer's user_agent (optional, never kept): the answer adds likely_on_another_device (lead with "Set Up {lock} on {device}" through new_phone/send instead of the passkey sheet), device (lock: "Face ID", "Touch ID", "Fingerprint or Screen Lock", "Windows Hello"; name: "This Phone"…) and code_approval_available. Never a dead end: if the sheet is cancelled or finds nothing, offer "Set Up {lock} on {device}" (new_phone) and, on a device that can't hold a passkey, "Approve With a Code" (code/send).
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
customer_contactobjectfields: label, email; How to reach the customer for a one-time code: label (the name on their passkey) and email. Kept 7 days, never in the signed record.
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.

POST/v1/incremental-charges/{id}/passkey/finish

Approve inside your app or on your website: send the signed answer. An answer made on one of your websites in passkey_websites.in_page is accepted and recorded as approved on your website, with its address; any other website is refused. Send ceremony_id and the passkey response from the phone. Wilby checks the signature against the customer's passkey; the incremental charge is approved (recorded as approved with Face ID in your app) and charged if Wilby charges for you. incremental_charge.approved follows.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
ceremony_id requiredstringup to 40 chars; The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing.
response requiredobjectThe browser's WebAuthn answer, passed through unchanged.
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.

POST/v1/incremental-charges/{id}/passkey/new_phone/send

Set up this device: text a code. Since 0.67.0, also when likely_on_another_device is true or the passkey sheet was cancelled or found nothing. For a customer who set up Face ID on another phone (begin gave authenticate, new_phone_available is true, but this phone has no passkey). Sends customer.code_requested to your webhook for you to text. Returns code_id.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.

POST/v1/incremental-charges/{id}/passkey/new_phone/verify

New phone: check the code, get a set-up prompt. Send code_id and code. A wrong code returns wrong_code with tries left. The right code returns a passkey_prompt with kind: register: create the passkey, send it to /passkey/finish, then call /passkey/begin again to approve. The customer's other passkeys keep working.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
code_id requiredstringup to 40 chars; The id of a sent code. Send it back with the code the customer types.
code requiredstringup to 12 chars; A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.

POST/v1/incremental-charges/{id}/code/send

Approve with a code alone: send the code. For a device that can't hold a passkey (no screen lock, an old browser). Sends customer.code_requested to your webhook for you to text (or Wilby texts it, if set up). The code is for this exact extra and amount. Returns code_id. Optional user_agent for the report by device (never kept).
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.

POST/v1/incremental-charges/{id}/code/verify

Approve with a code alone: check the code. Send code_id and code. A wrong code returns wrong_code with tries left. The right code approves the extra (decided_via: one_time_code, recorded as approved with a texted code) and incremental_charge.approved follows.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
code_id requiredstringup to 40 chars; The id of a sent code. Send it back with the code the customer types.
code requiredstringup to 12 chars; A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.

POST/v1/incremental-charges/{id}/passkey/report

Report what happened on the device. Optional. Tell Wilby what happened on your page or in your app, so "Approvals by Device" covers it: step (authenticate, register, setup, code), outcome (cancelled, no_passkey_here, failed, rescue_shown, rescue_setup, rescue_code, rescue_retry, rescue_other…), a short reason (the browser's error name) and the customer's user_agent. Only the device kind, browser and system are kept, 13 months. Answers 204.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
step requiredauthenticate register setup codeWhich step: begin, finish, set_up_send, set_up_verify, code_send, code_verify, report.
outcome requiredok cancelled no_passkey_here failed error wrong_code rescue_shown rescue_setup rescue_code rescue_retry rescue_otherHow it ended.
reasonstringup to 80 chars; Why, as a code or in words. On an incremental charge: the store's reason the customer sees.
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.

POST/v1/incremental-charges/{id}/approval-step

The approve helper's one route (Wilby.approve). Since 0.67.2. Your website loads /kit/v1/approve.js and calls Wilby.approve({ incrementalChargeId, send }); send posts the helper's body to your server, which forwards it here unchanged with your API key (only for the signed-in customer's own charge) and returns Wilby's answer, errors included. step is one of begin, finish, set_up_send, set_up_verify, code_send, code_verify, report; each does what the matching route above does. status: "approved" means the customer said yes, not that money moved: keep showing a charging state until your charge has had its chance, then show "Approved" or the decline. The helper runs the whole device side: Face ID / Touch ID / fingerprint, "Set Up {lock} on {device}" with a texted code, "Approve With a Code", and Wilby's page for browsers that can't (Safari before 18, Firefox). Your website must be in passkey_websites.in_page.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
step requiredbegin finish set_up_send set_up_verify code_send code_verify reportWhich step: begin, finish, set_up_send, set_up_verify, code_send, code_verify, report.
incremental_charge_idstringup to 40 chars; The incremental charge's id (top_…).
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.
ceremony_idstringup to 40 chars; The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing.
responseobjectThe browser's WebAuthn answer, passed through unchanged.
code_idstringup to 40 chars; The id of a sent code. Send it back with the code the customer types.
codestringup to 12 chars; A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.
report_stepauthenticate register setup codeWhich approval step is being reported.
outcomeok cancelled no_passkey_here failed error wrong_code rescue_shown rescue_setup rescue_code rescue_retry rescue_otherHow it ended.
reasonstringup to 80 chars; Why, as a code or in words. On an incremental charge: the store's reason the customer sees.

GET/v1/approval-attempts

Where approving gets stuck, by device. Last days (1–90, default 30), by device, browser and system, worst first: approved, cancelled, no passkey here, failed, set up here, and the most common reasons. Covers Wilby's page, the web script and your server's passkey steps. Also on the dashboard (Waiting).
ParameterInTypeNotes
daysqueryintegerA number of days, or the days of the week (0 = Sunday) for hours.

POST/v1/incremental-charges/{id}/link

Get a fresh approval link for a waiting incremental charge. To send it again. Earlier links for it stop working (they say a newer link was sent). Same answer-by time.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/incremental-charges/{id}/cancel

Withdraw a request the store sent. While it waits for the customer (for example the store typed the wrong amount), or after the customer approved it while nothing has been paid for it yet (you run the charges and the price changed, or the charge was declined). Nothing more is charged, the customer's link shows "Request Withdrawn", customer_status becomes withdrawn, the order goes back to where it was, and incremental_charge.cancelled is sent. Once a payment was reported for it, this is refused with already_paid: refund instead.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
reason requiredstringup to 300 chars; Why, as a code or in words. On an incremental charge: the store's reason the customer sees.

POST/v1/orders/{id}/tip-link

Get a tip link for the customer
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
valid_daysintegermin 1; max 30; How many days the link works.

POST/v1/orders/{id}/evidence

Add evidence to an order (a photo, a scale reading)
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
type requiredscale_reading photo receipt delivery customer_message device_record otherWhat kind it is.
sha256 requiredstringSHA-256 fingerprint.
file_refstringup to 500 chars; Your reference to a file you keep (a photo, a document). Wilby stores its fingerprint, not the file.
labelstringup to 120 chars; A short name shown to people.
metaobjectExtra details about a piece of evidence (your own keys and values).

Customer Permissions

Limits customers set for their own orders and for their AI agents.

POST/v1/customers/overage-link

Get a link where the customer sets their own limits. Optional return_url: where the page sends the customer after saving.
Body fieldTypeNotes
customer_external_ref requiredstringup to 200 chars; Your own id for the customer.
return_urlstringup to 500 chars; Where Wilby's pages send the customer when they are done (https, or your app's own link).

POST/v1/customers/mandate-link

Get a link where the customer gives an AI agent a limited permission, or sees and turns off their agents. With manage_only: true the link opens "Your AI Agents": every agent the customer allowed, what it ordered and spent, Turn Off, Turn Off All, and Get Proof (a signed, shareable proof of what they allowed, when they turned it off, and that nothing happened after). Put it behind a "Your AI Agents" button in your app: call this when the button is tapped, so each link is fresh.
Body fieldTypeNotes
customer_external_ref requiredstringup to 200 chars; Your own id for the customer.
payment_method_refstringup to 200 chars; Your processor's id for the customer's saved card or bank account.
agent_namestringup to 60 chars; The agent's display name, as the customer named it or as the platform reports it.
per_order_centsintegermin 100; max 10000000000; The most per order.
monthly_centsintegermin 100; max 10000000000; The most per month.
merchant_external_refsarrayYour own ids for the stores.
days30 90 180 365A number of days, or the days of the week (0 = Sunday) for hours.
valid_hoursintegermin 1; max 168; How many hours the link works.
manage_onlybooleanTrue for a link that only lets the customer manage existing permissions.
bankobjectfields: bank_name, account_last4, processor_mandate_ref, range_cents; Bank account details for an ACH debit authorization.

GET/v1/mandates

List agent permissions
ParameterInTypeNotes
customer_external_refquerystringYour own id for the customer.

POST/v1/mandates/{id}/revoke

Turn a permission off
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/customers/{ref}/contact

How to reach a customer for a one-time code, and the name on their passkey. email: where Wilby emails a one-time code when you don't text codes yourself (customers whose phone has no screen lock, and a customer's first setup). label: shown on their passkey ("Example Shop · Jane D."); without it the passkey is saved as "Your Example Shop Account" (your business name). Kept 7 days after you last send it, then deleted; never put in the signed record. The same block can go with an incremental charge (customer_contact on POST /v1/orders/{id}/incremental-charges), a screen pass, or the in-app approval.
ParameterInTypeNotes
ref requiredpathstringYour own id (in the address).
Body fieldTypeNotes
labelstring or nullup to 80 chars; A short name shown to people.
emailstring or nullup to 254 chars; An email address (shown masked when read back).

POST/v1/customers/{ref}/payment-method

Change a customer's saved payment method. When the customer changes their card in your app. Wilby charges the new one from the next payment on.
ParameterInTypeNotes
ref requiredpathstringYour own id (in the address).
Body fieldTypeNotes
payment_method_ref requiredstringup to 200 chars; Your processor's id for the customer's saved card or bank account.

GET/v1/customers/{ref}/overage

Get a customer's pre-approved overage. Also says whether they have chosen one yet (has_rule) and which choices to show them.
ParameterInTypeNotes
ref requiredpathstringYour own id (in the address).

POST/v1/customers/{ref}/overage

Change a customer's pre-approved overage from your app. Same or stricter than now: saved at once (confirmed in your app). Looser: answers 202 with a url where the customer confirms it themselves (Face ID or a code).
ParameterInTypeNotes
ref requiredpathstringYour own id (in the address).
Body fieldTypeNotes
preapproved_overage_pct requiredintegermin 0; max 50; How far above the amount the customer lets you charge without asking (percent).
approval_required_above_centsinteger or nullmin 100; max 100000000; Above this amount, the customer approves each incremental charge themselves.
return_urlstringup to 500 chars; Where Wilby's pages send the customer when they are done (https, or your app's own link).

Outside Agent Permissions

Permissions signed elsewhere: Google AP2, Mastercard Verifiable Intent, Agentic Commerce Protocol.

GET/v1/trusted-issuers

List agent platforms and card issuers whose permissions can be accepted

POST/v1/trusted-issuers/{id}/enable

Trust a platform or issuer for your stores
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/trusted-issuers/{id}/disable

Stop trusting a platform or issuer
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/mandates/{id}/credentials

Get the signed mandates for a permission
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/orders/{id}/credentials

Get the signed permissions kept with an order
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

Bank Payments

ACH debits with a signed customer authorization, returns and their health.

POST/v1/customers/ach-authorization-link

Get a link where the customer signs a bank debit authorization
Body fieldTypeNotes
customer_external_ref requiredstringup to 200 chars; Your own id for the customer.
payment_method_refstringup to 200 chars; Your processor's id for the customer's saved card or bank account.
railach instant_bankHow the money moves: card or ach.
bank_namestringup to 80 chars; The bank's name.
account_last4stringLast 4 digits of the bank account.
processor_mandate_refstringup to 200 chars; The bank mandate's id at your processor.
per_order_centsintegermin 100; max 50000000; The most per order.
range_centsinteger or nullmin 0; max 50000000; The allowed amount range.
monthly_centsintegermin 100; max 50000000; The most per month.
merchant_external_refsarrayYour own ids for the stores.
days90 180 365 730A number of days, or the days of the week (0 = Sunday) for hours.
valid_hoursintegermin 1; max 168; How many hours the link works.

GET/v1/ach-authorizations

List signed ACH debit authorizations
ParameterInTypeNotes
customer_external_refquerystringYour own id for the customer.

POST/v1/ach-authorizations/{id}/revoke

Revoke an ACH debit authorization
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/orders/{id}/retry-payment

Retry a returned bank debit (within Nacha's retry limits)
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/bank-returns/health

Return rates over the last 60 days, against Nacha thresholds
ParameterInTypeNotes
merchant_external_refquerystringYour own id for the store.

POST/v1/bank-accounts

Save and verify a customer's bank account (Braintree). Send the one-time token from Braintree's bank form. network_check verifies at once; micro_transfers sends two small deposits the customer confirms. If your Braintree account does not have network check turned on, the answer has error: verification_not_enabled: use micro_transfers or ask Braintree to turn it on.
Body fieldTypeNotes
merchant_external_ref requiredstringup to 200 chars; Your own id for the store.
token requiredstringup to 200 chars; A one-time token from your processor's bank account form.
verificationnetwork_check micro_transfersHow to verify it.

POST/v1/bank-accounts/confirm

Confirm the two test deposit amounts
Body fieldTypeNotes
merchant_external_ref requiredstringup to 200 chars; Your own id for the store.
verification_id requiredstringup to 200 chars; The bank account check's id.
amounts_cents requiredarrayThe two small test deposit amounts, in cents, that confirm a bank account.

Platform-Run Payments

For platforms that charge through their own processor: ask, charge, then report.

POST/v1/orders/{id}/approvals

Ask for a signed yes or no before charging
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
kind requiredauthorize charge capture void refund replace_holdWhat kind it is. On an approval: authorize, capture, charge or refund. On a payment report: what happened.
amount_cents requiredintegermin 0; max 10000000000; An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.

POST/v1/orders/{id}/hold

Take the hold in one call (agent orders). Since 0.68.0. Confirms the order if needed, asks Wilby for an authorize approval for amount_cents, and records your hold (processor, processor_ref, status), the same as /confirm, /approvals and /payments in a row. Use it for an order an agent placed through your storefront, after you answered /orders or when order.created arrives. If Wilby doesn't allow it: 409 not_allowed (release the hold, cancel your order).
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
amount_cents requiredintegermin 0; max 10000000000; An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.
processor requiredstringup to 40 chars; The payment processor (stripe, square, braintree, adyen, paypal).
processor_ref requiredstringup to 200 chars; The payment's id at the processor (for example a Stripe PaymentIntent).
status requiredsucceeded failed pendingWhere it stands. On an incremental charge: pending, approved, declined, expired, cancelled.
railcard ach instant_bank rtp fednow cash otherHow the money moves: card or ach.
failure_reasonstringup to 200 chars; Why it failed.

POST/v1/orders/{id}/payments

Report a payment you made. See the Platform Integration guide for what to report for each store action. When an AI agent paid, add agent_payment (paid_with: link_agent_wallet, mastercard_agent_pay, visa_intelligent_commerce, agent_one_time_token, paypal_wallet, google_pay, saved_card, bank_debit or other; optional agent and reference): recorded as reported by you. A payment the customer chose themselves (tip, something they added, a payment link they paid) is sent with customer_initiated: it needs no approval and never counts toward their limit. For an incremental charge, send incremental_charge_id. A failed charge for an approved extra: status: "failed" with incremental_charge_id and failure_reason; the incremental charge shows "Approved, Payment Failed" until a later charge with the same incremental_charge_id pays it.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
kind requiredauthorize charge capture void refund replace_holdWhat kind it is. On an approval: authorize, capture, charge or refund. On a payment report: what happened.
amount_cents requiredintegermin 0; max 10000000000; An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.
processor requiredstringup to 40 chars; The payment processor (stripe, square, braintree, adyen, paypal).
processor_ref requiredstringup to 200 chars; The payment's id at the processor (for example a Stripe PaymentIntent).
status requiredsucceeded failed pendingWhere it stands. On an incremental charge: pending, approved, declined, expired, cancelled.
approval_idstringThe id of the approval Wilby gave (the signed yes for a payment).
incremental_charge_idstringThe incremental charge's id (top_…).
failure_reasonstringup to 200 chars; Why it failed.
railcard ach instant_bank rtp fednow cash otherHow the money moves: card or ach.
paid_withchatgpt_walletHow it was paid (card, Google Pay, bank, agent token).
agent_requestobjectfields: signature_input, signature, signature_agent, authority, path; The agent's signed HTTP request (RFC 9421 message signature) that asked for the payment.
payment_account_referencestringup to 64 chars; The card network's Payment Account Reference (PAR), when your processor gives it.
agent_paymentobjectfields: paid_with, agent, reference; The payment as the agent platform made it (for agent-paid orders): how it was paid and its reference.
customer_initiatedobjectfields: purpose, note; A payment the customer started themselves after the order (tip, add_on, payment_link, other).

POST/v1/payments/{id}/bank-outcome

Report how a bank debit ended (cleared or returned)
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
status requiredsucceeded returnedWhere it stands. On an incremental charge: pending, approved, declined, expired, cancelled.
return_codestringThe bank's return code (for example R01).

Disputes

Chargebacks and the signed evidence sent with them.

POST/v1/orders/{id}/disputes

Record a chargeback
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
reason requiredovercharged not_delivered damaged otherWhy, as a code or in words. On an incremental charge: the store's reason the customer sees.
notestringup to 500 chars; A note in plain words.

GET/v1/disputes/{id}

Get a dispute and its evidence
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/disputes/{id}/resolve

Record how a dispute ended
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
outcome requiredmerchant_won customer_refundedHow it ended.
refund_centsintegermin 0; max 10000000000; An amount to refund, in cents. On a dispute: how much was refunded.
note requiredstringup to 500 chars; A note in plain words.

Records

Signed records anyone can check.

POST/v1/orders/{id}/receipt-link

Get the order's verify link. A link anyone can open to check the order's signed record.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
valid_daysintegermin 1; max 130; How many days the link works.
return_urlstringup to 500 chars; Where Wilby's pages send the customer when they are done (https, or your app's own link).

Reports

Totals, daily figures, stores and order exports, and live dashboards to share. Exports carry no customer names or contact details.

GET/v1/analytics/summary

Totals for a date range
ParameterInTypeNotes
fromquerystringStart date (YYYY-MM-DD) or start of the range.
toquerystringEnd date (YYYY-MM-DD) or end of the range.
merchant_idquerystringWilby's id for the store (mer_…).
tzquerystringAn IANA time zone, like America/New_York.

GET/v1/analytics/daily

Day-by-day figures
ParameterInTypeNotes
fromquerystringStart date (YYYY-MM-DD) or start of the range.
toquerystringEnd date (YYYY-MM-DD) or end of the range.
merchant_idquerystringWilby's id for the store (mer_…).
tzquerystringAn IANA time zone, like America/New_York.

GET/v1/analytics/stores

Figures per store
ParameterInTypeNotes
fromquerystringStart date (YYYY-MM-DD) or start of the range.
toquerystringEnd date (YYYY-MM-DD) or end of the range.
merchant_idquerystringWilby's id for the store (mer_…).
tzquerystringAn IANA time zone, like America/New_York.

GET/v1/analytics/orders.csv

Export orders as CSV (no customer names or contact details)
ParameterInTypeNotes
fromquerystringStart date (YYYY-MM-DD) or start of the range.
toquerystringEnd date (YYYY-MM-DD) or end of the range.
merchant_idquerystringWilby's id for the store (mer_…).
tzquerystringAn IANA time zone, like America/New_York.

POST/v1/analytics/dashboard-link

Make a private live-dashboard link (for one store or all)
Body fieldTypeNotes
merchant_idstringup to 40 chars; Wilby's id for the store (mer_…).
valid_hoursintegermin 1; max 720; How many hours the link works.
labelstringup to 80 chars; A short name shown to people.
tzstringup to 64 chars; An IANA time zone, like America/New_York.

POST/v1/dashboard/open

Open Dashboard from your admin (one-time link). Returns a one-time url (15 minutes) to the hosted Dashboard: orders, waiting, AI agents, settings. Name the staff member in staff_name; with can_edit they may change which agents may order, signed under their name. Opens an 8-hour session.
Body fieldTypeNotes
staff_name requiredstringup to 80 chars; The name of the person opening the Dashboard.
staff_refstringup to 120 chars; Your id for that person.
can_editbooleanWhether this dashboard link can change settings (or only view).
merchant_idstringup to 40 chars; Wilby's id for the store (mer_…).
tzstringup to 64 chars; An IANA time zone, like America/New_York.
pageoverview orders waiting assistants readiness listing setupWhich page to open.
order_idstringThe order's id (prm_…).

Ready-Made Screens

Wilby's customer screens on your own website (/kit/v1/wilby.js): your server asks for a screen pass; the screens call /v1/client with it. One customer, 30 minutes, no money moves.

POST/v1/screen-sessions

Get a screen pass for one customer. Call from your server (never the browser) and put client_secret on the page: <wilby-order-card client-secret="wcs_…" order-id="prm_…"> or Wilby.init({clientSecret}). Up to 30 minutes (valid_minutes); order_id limits it to one order. It works only from your screen_origins (POST /v1/settings) and Wilby's own address; a request with no Origin (a phone app) is allowed. It can read this customer's orders and rule, save the same or a stricter rule, decline an incremental charge and turn an agent off. Approving an incremental charge or a looser rule opens a small Wilby window where the customer confirms it's them.
Body fieldTypeNotes
customer_external_ref requiredstringup to 200 chars; Your own id for the customer.
order_idstringThe order's id (prm_…).
valid_minutesintegermin 5; max 30; How many minutes it works.
customer_contactobjectfields: label, email; How to reach the customer for a one-time code: label (the name on their passkey) and email. Kept 7 days, never in the signed record.

GET/v1/client/session

The business's look and words, and the customer's rule (screen pass)

GET/v1/client/orders

This customer's orders (screen pass)
ParameterInTypeNotes
limitqueryintegerHow many to return (paging).

GET/v1/client/orders/{id}

One order's screen-ready block (screen pass)
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/client/overage

Save the customer's rule (screen pass). The same or stricter: saved at once, recorded as confirmed on the business's website. Looser: status: needs_customer with window_url, the Wilby window where the customer confirms it's them.
Body fieldTypeNotes
preapproved_overage_pct requiredintegermin 0; max 100; How far above the amount the customer lets you charge without asking (percent).
approval_required_above_centsinteger or nullmin 0; Above this amount, the customer approves each incremental charge themselves.
app_returnstringup to 300 chars; Your app's own link to return to after a Wilby screen (for example yourapp://done).

POST/v1/client/incremental-charges/{id}/decline

Decline an incremental charge (screen pass). Charges nothing; recorded as declined on the business's website.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/client/incremental-charges/{id}/window

Open the Wilby window to approve an incremental charge (screen pass). A fresh approval page (earlier links for this incremental charge then say "Newer Link Sent"). Opened with ?w=<your origin>, it tells your page when the customer is done (postMessage {wilby: "window_done", state}) and closes.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
app_returnstringup to 300 chars; Your app's own link to return to after a Wilby screen (for example yourapp://done).

POST/v1/client/incremental-charges/{id}/passkey/begin

In your app: start the phone's own Face ID approval (screen pass). For apps registered with apps in POST /v1/settings (session.in_app_passkey is true), or from your own website when it is in screen_origins and on Wilby's /.well-known/webauthn list (session.in_page_passkey is true; the web script does this for you). Same as POST /v1/incremental-charges/{id}/passkey/begin, with the screen pass instead of your API key.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/client/incremental-charges/{id}/passkey/finish

In your app: finish the Face ID approval (screen pass)
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
ceremony_id requiredstringup to 40 chars; The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing.
response requiredobjectThe browser's WebAuthn answer, passed through unchanged.

POST/v1/client/incremental-charges/{id}/passkey/new_phone/send

In your app: new phone, send a code (screen pass)
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/client/incremental-charges/{id}/passkey/new_phone/verify

In your app: new phone, check the code (screen pass)
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
code_id requiredstringup to 40 chars; The id of a sent code. Send it back with the code the customer types.
code requiredstringup to 12 chars; A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.

GET/v1/client/agents

The customer's AI agents (screen pass)

POST/v1/client/agents/{id}/off

Turn an agent off (screen pass). Takes effect at once. Turning one back on needs the customer's own confirmation, on Wilby's Your AI Agents page.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

Webhooks

Signed notifications for every step.

GET/v1/event-types

List event types

POST/v1/webhook-endpoints

Add a webhook endpoint. Returns the signing secret once.
Body fieldTypeNotes
url requiredstringup to 500 chars; An address.
eventsarrayWebhook event types to send (order.*, incremental_charge.approved…), or * for all.
descriptionstringup to 200 chars; Plain text describing it. On an order: what was ordered.

GET/v1/webhook-endpoints

List webhook endpoints

POST/v1/webhook-endpoints/{id}

Update a webhook endpoint
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
urlstringup to 500 chars; An address.
eventsarrayWebhook event types to send (order.*, incremental_charge.approved…), or * for all.
descriptionstringup to 200 chars; Plain text describing it. On an order: what was ordered.
enabledbooleanWhether it is turned on.

DELETE/v1/webhook-endpoints/{id}

Remove a webhook endpoint
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/webhook-endpoints/{id}/rotate-secret

Rotate an endpoint's signing secret
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/webhook-endpoints/{id}/test

Send a signed test ping
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/webhook-deliveries

List deliveries and their results
ParameterInTypeNotes
order_idquerystringThe order's id (prm_…).
endpoint_idquerystringA webhook endpoint's id.
statusquerystring: pending delivered failed cancelledWhere it stands. On an incremental charge: pending, approved, declined, expired, cancelled.
limitqueryintegerHow many to return (paging).

POST/v1/webhook-deliveries/{id}/retry

Retry a delivery now
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

Sandbox

Test-only helpers. Refused with live keys.

POST/v1/sandbox/test-store

Make a fresh test store. Sandbox records are permanent like live ones, so instead of resetting, start over with a new store.
Body fieldTypeNotes
namestringup to 80 chars; A name.

POST/v1/sandbox/payments-path

Switch who charges the card in your sandbox. wilby_charges (Wilby holds and charges through your processor account) or you_charge (you charge with your own processor and report). Applies at once.
Body fieldTypeNotes
path requiredwilby_charges you_chargeWhich way to integrate, or a path.

GET/v1/sandbox/emails

Emails Wilby would have sent to test addresses. Codes emailed to reserved test addresses (example.com, .test, .example, .invalid) are kept here instead of sent, newest first, for one day. Filter with to.
ParameterInTypeNotes
toquerystringEnd date (YYYY-MM-DD) or end of the range.

POST/v1/sandbox/outside-mandates

Sign a test AP2, Verifiable Intent or ACP permission. Uses built-in test issuers so you can try outside permissions end to end.
Body fieldTypeNotes
formatap2 vi acpThe format of the file or credential.
user_public_jwkobjectTest tools: the customer device's public key (P-256 JWK).
complete_requeststringup to 60000 chars; The full signed request the agent platform sent, for Wilby to check.
agent_public_jwkobjectTest tools: the agent's public key (P-256 JWK) for a test credential.
per_order_centsintegermin 100; max 10000000000; The most per order.
monthly_centsintegermin 100; max 10000000000; The most per month.
merchant_external_refsarrayYour own ids for the stores.
daysintegermin 1; max 365; A number of days, or the days of the week (0 = Sunday) for hours.

POST/v1/sandbox/bank-reconcile

Clear or return pending test bank debits now

Agent API

For AI agents acting for a customer (also available as an MCP server at /mcp).

POST/agent/v1/connect

Connect with the customer's code. Exchanges the 8-character code the customer gives the agent for an agent key.
Body fieldTypeNotes
code requiredstringup to 20 chars; A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.

GET/agent/v1/me

What this agent may do (limits left)

GET/agent/v1/stores

Stores this agent may order from

GET/agent/v1/orders

List this agent's orders

POST/agent/v1/orders

Place an order inside the customer's permission. Above a limit the answer is needs_customer with the reason: the customer decides, not the agent.
Body fieldTypeNotes
store_id requiredstringup to 40 chars; The store's id.
description requiredstringup to 300 chars; Plain text describing it. On an order: what was ordered.
amount_cents requiredintegermin 100; An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.

GET/agent/v1/orders/{id}

Get an order
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/agent/v1/orders/{id}/approve-extra

Approve an incremental charge inside the customer's permission
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
request_id requiredstringup to 40 chars; The sign-in request's id (oar_… or csi_…).

GET/agent/v1/orders/{id}/proof

Proof the order stayed inside the permission
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/agent/v1/orders/{id}/cancel

Cancel an order
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

Agent Storefront

Your stores in Claude and ChatGPT under your name: customers sign in with your account, Wilby runs the limits, approvals and records.

POST/v1/settings/google-orders

Save your Google key for order updates (UCP). {"google_partner_id", "api_key"} from Google's UCP onboarding. Sealed and never shown again (GET /v1/settings shows the platform id and the key's last 4). For orders Google places, Wilby sends Google: order placed, shipped and delivered (with tracking), cancellations, refunds and disputes.
Body fieldTypeNotes
google_partner_id requiredstringup to 100 chars; Your Google partner id.
api_key requiredstringup to 300 chars; A key you got from another service (Google order updates, a processor). Kept on Wilby's server; never shown again.

DELETE/v1/settings/google-orders

Remove your Google key for order updates

GET/v1/ucp/order-updates

Order updates sent to platforms and Google (UCP). The last 100, with what each answered. needs_attention=true: only updates Google refused (4xx), which are never retried unchanged; fix the cause (often a missing tracking link or the key) and report the order again.
ParameterInTypeNotes
needs_attentionquerybooleanList only what needs your attention.

POST/v1/ucp/link-clients

Register a platform for account linking (UCP). {"name": "Google", "redirect_uris": [...], "auth_method": "client_secret_basic" | "private_key_jwt", "jwks_uri"}. Returns client_id and, for client_secret_basic, client_secret (shown once). Enter them in the platform's account-linking setup (Google: Merchant Center).
Body fieldTypeNotes
namestringup to 60 chars; A name.
redirect_uris requiredarrayThe platform's return addresses for account linking (https).
auth_methodclient_secret_basic private_key_jwtHow the platform signs in to Wilby's account linking: client_secret_basic or private_key_jwt.
jwks_uristringup to 500 chars; The https address where the platform publishes its public keys.

POST/v1/ucp/link-clients/{id}/disable

Turn a platform's account linking off. Every customer's link through it ends (each permission revoked, signed on the customer's record) and its tokens stop working.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/storefront/secret

Create the storefront secret. Wilby signs every call to your Storefront API with it (Wilby-Signature header; Openhold-Signature is also sent during the move; same scheme as webhooks). Shown once; a new one replaces the old.

POST/v1/storefront/sign-ins

Tell Wilby who signed in. Your login page got openhold_request; after the customer signs in with their normal account, send request_id and your customer_external_ref (and payment_method_ref, their saved card, if Wilby takes the payment for you). Redirect the customer to the continue_url you get back (they set the agent's limits there, in your look).
Body fieldTypeNotes
request_id requiredstringThe sign-in request's id (oar_… or csi_…).
customer_external_ref requiredstringup to 200 chars; Your own id for the customer.
payment_method_refstringup to 200 chars; Your processor's id for the customer's saved card or bank account.

GET/v1/merchants/{id}/agent-rules

One store's own rules for AI agent orders. The store's own rules (store) and what applies there (applies: the stricter of the business's and the store's, the store's hours if set, and the agents it turns away).
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/merchants/{id}/agent-rules

Set one store's rules for AI agent orders (stricter only). Any of max_order_cents, always_approval_required_above_cents, hours ({days 0-6, start, end, tz}) and blocked_agents. Null clears a rule. A store can only be stricter than the business (the smaller amount wins; its hours replace the business's). Signed with the change.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).
Body fieldTypeNotes
max_order_centsinteger or nullThe most an AI agent may order at once from you.
always_approval_required_above_centsinteger or nullAbove this amount, the customer always approves the order themselves, whatever their limits.
hoursobject or nullWhen AI agents may order: tz (IANA time zone), days (0 = Sunday), start and end (HH:MM).
blocked_agentsarrayRefused AI agent orders, by agent.

GET/v1/storefront/readiness

Agent Readiness Check: how ready each store is for AI agents. Asks your Storefront API what an agent would see (stores, services, prices, open times; nothing is ordered or quoted) and checks your settings. Returns a score out of 100 per store and for the business, and each check with what to fix. Optional store_ref for one store. Also in Dashboard under Agent Readiness.
ParameterInTypeNotes
store_refquerystringYour id for the store.

GET/v1/storefront/full-test

Full Storefront Test: the whole agent script against one store. Since 0.69.0. Free, on Wilby's server, in seconds. Plays what an AI agent does (find the store, read it, open times, quotes with a tip, a bad promo code, no time, a taken time, an unknown item, a mixed basket, then status and cancel for an unknown order) with price_check_only: true, so nothing is ordered or kept. Checks the contract, the things real AI apps misread, and the directory rules for your connector. store_ref picks the store (default: your first). near (since 0.70.3) is a ZIP or place to search near when your store search asks for a location; without it, the store's own ZIP from /store is used. Each step has status (pass, warn, fail, skipped), what happened and what to fix.
ParameterInTypeNotes
store_refquerystringYour id for the store.
nearquerystringA ZIP code, address or place to search stores near (on /stores and, since 0.70.3, on the full storefront test).

GET/v1/storefront/listing

Get Listed: materials for each AI app's directory. Puts together what each directory asks for from your settings (name, one-line summary, description, icon, privacy policy, support, help page, example prompts, reviewer steps, tool labels) with a checklist: Done, Check This or Missing. Your privacy policy link is opened to check that it works. Set the materials with POST /v1/settings {"listing": {"one_liner", "long_description", "privacy_url", "support", "docs_url", "example_prompts", "reviewer_customer_ref", "reviewer_steps"}}. reviewer_customer_ref: a test customer in your system for directory reviewers; Wilby skips the first-setup code for that one customer (they still confirm with their device's lock). Also in Dashboard under Get Listed. Since 0.71.0: Gemini and Grok, your own address (own_address), ready-made answers (money_answer, data_handling, compliance, privacy_section), and calls from the reviewer account carry reviewer: true (its orders are cancelled after 30 minutes).

GET/v1/storefront/domain

Your own connector address. Since 0.71.0. Your own address for your connector (for example agents.yourbusiness.com): host, status (none, pending, verified or active), the two dns_records to add (CNAME to Wilby, TXT to show it's yours), connector_url, last_error from the last check. active means the security certificate is in place and the connector answers there.

POST/v1/storefront/domain

Choose your own connector address. Since 0.71.0. {"host": "agents.yourbusiness.com"}: an address under your own domain (not the domain itself, so your website stays where it is). Answers with the two DNS records to add. Choosing another address replaces the first. Refusals: invalid_host, host_taken.
Body fieldTypeNotes
host requiredstringup to 253 chars; The website address where it happened.

DELETE/v1/storefront/domain

Remove your own connector address. Since 0.71.0. Your connector keeps working on Wilby's address.

POST/v1/storefront/domain/check

Check your DNS records. Since 0.71.0. Looks up both DNS records now. Both found: verified; Wilby then gets the security certificate by itself and the address turns active, usually within minutes (check again any time; certificate shows where it is). Not found: stays pending, with what's missing in last_error. DNS changes can take up to an hour to show.

AI Agents on Your Website

See which AI agents browse your own website, apply your rules and the customer's limits at checkout, and record the agent on the order. The visit check uses a website key (wk_…) that can do nothing else.

POST/v1/website-keys

Create a website key. A website key (wk_…) can only call POST /v1/agent-checks: it can't read orders, charge or change anything, so it is safe on a web server or in a Cloudflare Worker. Shown once. Optional name.
Body fieldTypeNotes
namestringup to 60 chars; A name.

GET/v1/website-keys

List your website keys. Their start (key_prefix), when each was made and last used, and whether it was revoked. Never the keys themselves.

POST/v1/website-keys/{id}/revoke

Revoke a website key. It stops working at once on this server and within a minute everywhere.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/agent-checks/report

Agents on your website. Last 30 days (or days, up to 90), per agent: visits by level, and how many reached checkout, ordered or were turned away. Daily totals only, kept 13 months: no IP addresses, pages or shoppers.
ParameterInTypeNotes
daysqueryintegerA number of days, or the days of the week (0 = Sunday) for hours.

GET/v1/agent-checks/{id}

One check and what came of it. The level, agent and clue (with browser_signals and buyer_hints when there were any), whether it was allowed, the order it was used for, and whether the customer still has to approve that order.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

POST/v1/agent-checks

Who is visiting (website key). Called by your server or Worker with Authorization: Bearer wk_…. Send stage (page in the background, or checkout), host, path, and what you have: user_agent, ip (used once, never stored), signature, signature_input, signature_agent and the signed headers, bot_score (1–99, below 30 means automated) or automated, the forwarded header (read only when the signature checks out), and at checkout browser_signals (the wilby_signals field from /agent-signals.js on your checkout page). Answer: level (verified, named_itself, likely_agent or no_sign_of_agent; never "human"), agent, clue, signed_for for signed requests tagged for browsing or paying, browser_signals (what the page script found), buyer_hints (a verified agent's buyer country, time zone and language), allowed (your Agent Access Policy, with message when not), your rules, and at checkout an id (ach_…, 30 minutes, once) to pass as agent_check_id on POST /v1/orders. Treat a slow or failed answer as no sign of an agent.
Body fieldTypeNotes
stage requiredpage checkoutWhere the order is: created, confirmed, authorized, captured, cancelled, expired, disputed.
methodstringup to 10 chars; The HTTP method of the signed request.
host requiredstringup to 300 chars; The website address where it happened.
path requiredstringup to 2000 chars; Which way to integrate, or a path.
querystringup to 2000 chars; The query string of the signed request.
user_agentstringup to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.
ipstringup to 64 chars; The visitor's IP address (used only for the check, not kept in the record).
bot_scoreintegermin 1; max 99; Your bot tool's score for the visitor (1–99; below 30 means automated, as Cloudflare scores it).
automatedbooleanYour own bot detection result: true when you think the visitor is automated.
signaturestringup to 4000 chars; The signature.
signature_inputstringup to 4000 chars; The Signature-Input header of the signed request.
signature_agentstringup to 500 chars; The Signature-Agent header (who the agent says it is).
headersobjectThe request headers that were signed.
browser_signalsstringup to 2000 chars; Signs of an AI agent working inside the customer's own browser, from /agent-signals.js on the checkout page. In a request: the wilby_signals summary (counts and yes/no markers only). In an answer: sent and found (each with id, label and strength: strong or weak). Never makes a check "verified".
forwardedstringup to 2000 chars; The visitor's Forwarded header, as received. Only country, time zone and language are read from it, and only when the request's signature checks out.

Public

No key needed: verification keys, records and daily checkpoints.

GET/v1/keys

Public signing keys

GET/v1/public/audit-trail/{id}

An order's signed record (with its verify code `k`)
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/public/agent-proof/{id}

Proof for one AI agent (with its code `k`). What the customer allowed (signed with Face ID or a code), when it was turned off, every order it made, and whether anything happened after. The same proof the customer gets from "Get Proof"; the human-readable page is /agent-proof/{id}?k=…
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/public/evidence-package/{id}

Claim packet for an order the customer reported (with its code `k`). For an order the customer said their AI agent got wrong: what the customer allowed, what the agent did, the report, and what the business did about it, each with its signed record. The finding is always authorized_but_wrong. The page at /claim-packet/{id}?k= prints to one page. The link is in order.reported_wrong.claim_packet_url.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/public/quotes/{id}

A signed quote (with its code `k`). The price an AI agent was quoted, signed by Wilby: the document, whether the signature checks out, and what became of it (open, expired, or the order with its final price and whether it stayed within the quote). The page is at /quote/{id}?k=. The link comes back from quote_order as signed_quote.verify_url and on the order as order.signed_quote.url.
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/public/checkpoints

Daily public checkpoints

GET/v1/public/checkpoints/{id}

One checkpoint, its signed text and signature
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/public/checkpoints/{id}/body

The exact signed text of a checkpoint
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).

GET/v1/public/checkpoints/{id}/ots

The Bitcoin timestamp proof (.ots) of a checkpoint
ParameterInTypeNotes
id requiredpathstringWilby's id for it (a prefix plus 20 characters, like prm_… for an order).