API Reference
Built from the server's own request rules, so it matches what the API accepts. Base URL https://app.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.
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 field | Type | Notes |
|---|
external_ref required | string | up to 200 chars; Your own id for it. |
name required | string | up to 200 chars; A name. |
processor required | string | up to 40 chars; The payment processor (stripe, square, braintree, adyen, paypal). |
processor_account_ref required | string | up to 200 chars; The store's account id at its processor. |
settings | object | Settings 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.
| Parameter | In | Type | Notes |
|---|
ref required | path | string | Your own id (in the address). |
| Body field | Type | Notes |
|---|
processor required | square braintree adyen paypal | The 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)
| Parameter | In | Type | Notes |
|---|
ref required | path | string | Your 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.
| Parameter | In | Type | Notes |
|---|
ref required | path | string | Your own id (in the address). |
| Body field | Type | Notes |
|---|
processor required | square braintree adyen paypal | The 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 field | Type | Notes |
|---|
stripe_key required | string | up 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 field | Type | Notes |
|---|
return_url | string or null | up to 500 chars; Where Wilby's pages send the customer when they are done (https, or your app's own link). |
wording | object | Your own lines on customer pages (keys like extra_title; null goes back to Wilby's default). |
storefront | object | fields: 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. |
apps | object | fields: ios, android; Your iOS and Android apps, so customers can approve inside your app. |
agent_rules | object or null | Your own rules for AI agent orders, stricter than the customer's: max_order_cents, always_approval_required_above_cents, hours. |
embed_origins | array | Your websites that may show the Dashboard inside your own dashboard (up to 5 https origins). |
screen_origins | array | Your websites where Wilby's ready-made screens run (up to 10 https origins). |
first_setup_code | boolean | Before a customer's first passkey, a one-time code proves it's them (default true). |
variable_amount | boolean | Whether your final price can change after checkout (default false). |
ucp | object | fields: 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. |
listing | object | fields: 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_access | object | fields: mode, verified_only, allowed, blocked; Which AI agents may order from you: mode all or only, allowed, blocked, verified_only. |
website_agents | object | fields: likely; AI agents on your own website: likely (record_only or ask_customer). |
rule_choices_pct | array | The percent choices offered to customers for extra charges (1 to 4). |
recommended_pct | 5 10 15 20 25 30 40 50 | The choice shown as recommended. |
branding | object | fields: 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 field | Type | Notes |
|---|
merchant_external_ref required | string | up to 200 chars; Your own id for the store. |
customer required | object | fields: external_ref, payment_method_ref; The customer: external_ref (your id for them), and optionally payment_method_ref and customer_contact. |
external_ref | string | up to 200 chars; Your own id for it. |
display_ref | string | up to 40 chars; Your order number as customers know it (shown on Wilby's pages). |
purpose required | string | up to 500 chars; What the order is for, in plain words. |
order_type | string | up to 60 chars; Your kind of order (your own word). |
pricing_terms | object | Your pricing terms for the order (your own keys), shown to the customer. |
currency | string | The currency (USD). |
amount_cents required | integer | min 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_cents | integer | min 0; max 10000000000; The most that may be charged for the order without asking the customer again. |
expires_at | string | up to 40 chars; When it expires (ISO 8601, UTC). |
estimate_basis | object | fields: source, entered_amount_cents; How you worked out the estimate (for example "by weight"). |
agent_mandates | object | fields: 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_signature | object | fields: 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_id | string | The 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.
| Parameter | In | Type | Notes |
|---|
customer_external_ref | query | string | Your own id for the customer. |
merchant_external_ref | query | string | Your own id for the store. |
stage | query | string | Where the order is: created, confirmed, authorized, captured, cancelled, expired, disputed. |
limit | query | integer | How many to return (paging). |
before | query | string | List 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.
| Parameter | In | Type | Notes |
|---|
merchant_external_ref required | query | string | Your own id for the store. |
customer_external_ref | query | string | Your own id for the customer. |
amount_cents required | query | integer | 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. |
card_funding | query | string: credit debit prepaid | The 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
POST/v1/orders/{id}/confirm
Store confirms the order
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
capture_cents required | integer | min 0; max 10000000000; The final amount captured for the order. |
measure | object | fields: 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
reason | string | up 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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
amount_cents required | integer | min 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 required | string | up 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).
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
type required | shipped delivered | What kind it is. |
tracking_number | string | up to 100 chars; The shipment's tracking number. |
tracking_url | string | up to 500 chars; The tracking page (https). |
carrier | string | up to 60 chars; The shipping company. |
description | string | up to 200 chars; Plain text describing it. On an order: what was ordered. |
line_items | array | The 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
statements required | array | Statements only the customer can confirm (for example "I am 21 or older"). |
valid_hours | integer | min 1; max 168; How many hours the link works. |
return_url | string | up 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).
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
amount_cents required | integer | min 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 required | over_estimate add_on special_handling damage_fee other extra_parts extra_labor substitution price_change | Why, as a code or in words. On an incremental charge: the store's reason the customer sees. |
note | string | up to 500 chars; A note in plain words. |
before_work | boolean | True when the incremental charge is asked before the work is done (the customer sees "before we continue"). |
approval_window_minutes | integer | min 5; max 1440; How long the customer has to answer an incremental charge request (minutes). |
reason_title | string | up to 80 chars; A short title for the reason (shown as the heading). |
card_label | string | up to 40 chars; How the card is shown to the customer, like "Visa •••• 4242". |
return_url | string | up to 500 chars; Where Wilby's pages send the customer when they are done (https, or your app's own link). |
agent_mandates | object | fields: 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_signature | object | fields: 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_contact | object | fields: 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 required | array | Proof 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
amount_cents required | integer | min 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
note | string | up 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).
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
customer_contact | object | fields: 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_agent | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
ceremony_id required | string | up to 40 chars; The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing. |
response required | object | The browser's WebAuthn answer, passed through unchanged. |
user_agent | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
user_agent | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
code_id required | string | up to 40 chars; The id of a sent code. Send it back with the code the customer types. |
code required | string | up to 12 chars; A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call. |
user_agent | string | up 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).
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
user_agent | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
code_id required | string | up to 40 chars; The id of a sent code. Send it back with the code the customer types. |
code required | string | up to 12 chars; A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call. |
user_agent | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
step required | authenticate register setup code | Which step: begin, finish, set_up_send, set_up_verify, code_send, code_verify, report. |
outcome required | ok cancelled no_passkey_here failed error wrong_code rescue_shown rescue_setup rescue_code rescue_retry rescue_other | How it ended. |
reason | string | up to 80 chars; Why, as a code or in words. On an incremental charge: the store's reason the customer sees. |
user_agent | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
step required | begin finish set_up_send set_up_verify code_send code_verify report | Which step: begin, finish, set_up_send, set_up_verify, code_send, code_verify, report. |
incremental_charge_id | string | up to 40 chars; The incremental charge's id (top_…). |
user_agent | string | up to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device. |
ceremony_id | string | up to 40 chars; The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing. |
response | object | The browser's WebAuthn answer, passed through unchanged. |
code_id | string | up to 40 chars; The id of a sent code. Send it back with the code the customer types. |
code | string | up to 12 chars; A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call. |
report_step | authenticate register setup code | Which approval step is being reported. |
outcome | ok cancelled no_passkey_here failed error wrong_code rescue_shown rescue_setup rescue_code rescue_retry rescue_other | How it ended. |
reason | string | up 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).
| Parameter | In | Type | Notes |
|---|
days | query | integer | A 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
reason required | string | up 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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
valid_days | integer | min 1; max 30; How many days the link works. |
POST/v1/orders/{id}/evidence
Add evidence to an order (a photo, a scale reading)
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
type required | scale_reading photo receipt delivery customer_message device_record other | What kind it is. |
sha256 required | string | SHA-256 fingerprint. |
file_ref | string | up to 500 chars; Your reference to a file you keep (a photo, a document). Wilby stores its fingerprint, not the file. |
label | string | up to 120 chars; A short name shown to people. |
meta | object | Extra 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 field | Type | Notes |
|---|
customer_external_ref required | string | up to 200 chars; Your own id for the customer. |
return_url | string | up 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 field | Type | Notes |
|---|
customer_external_ref required | string | up to 200 chars; Your own id for the customer. |
payment_method_ref | string | up to 200 chars; Your processor's id for the customer's saved card or bank account. |
agent_name | string | up to 60 chars; The agent's display name, as the customer named it or as the platform reports it. |
per_order_cents | integer | min 100; max 10000000000; The most per order. |
monthly_cents | integer | min 100; max 10000000000; The most per month. |
merchant_external_refs | array | Your own ids for the stores. |
days | 30 90 180 365 | A number of days, or the days of the week (0 = Sunday) for hours. |
valid_hours | integer | min 1; max 168; How many hours the link works. |
manage_only | boolean | True for a link that only lets the customer manage existing permissions. |
bank | object | fields: bank_name, account_last4, processor_mandate_ref, range_cents; Bank account details for an ACH debit authorization. |
GET/v1/mandates
List agent permissions
| Parameter | In | Type | Notes |
|---|
customer_external_ref | query | string | Your own id for the customer. |
POST/v1/mandates/{id}/revoke
Turn a permission off
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
ref required | path | string | Your own id (in the address). |
| Body field | Type | Notes |
|---|
label | string or null | up to 80 chars; A short name shown to people. |
email | string or null | up 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.
| Parameter | In | Type | Notes |
|---|
ref required | path | string | Your own id (in the address). |
| Body field | Type | Notes |
|---|
payment_method_ref required | string | up 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.
| Parameter | In | Type | Notes |
|---|
ref required | path | string | Your 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).
| Parameter | In | Type | Notes |
|---|
ref required | path | string | Your own id (in the address). |
| Body field | Type | Notes |
|---|
preapproved_overage_pct required | integer | min 0; max 50; How far above the amount the customer lets you charge without asking (percent). |
approval_required_above_cents | integer or null | min 100; max 100000000; Above this amount, the customer approves each incremental charge themselves. |
return_url | string | up 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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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 field | Type | Notes |
|---|
customer_external_ref required | string | up to 200 chars; Your own id for the customer. |
payment_method_ref | string | up to 200 chars; Your processor's id for the customer's saved card or bank account. |
rail | ach instant_bank | How the money moves: card or ach. |
bank_name | string | up to 80 chars; The bank's name. |
account_last4 | string | Last 4 digits of the bank account. |
processor_mandate_ref | string | up to 200 chars; The bank mandate's id at your processor. |
per_order_cents | integer | min 100; max 50000000; The most per order. |
range_cents | integer or null | min 0; max 50000000; The allowed amount range. |
monthly_cents | integer | min 100; max 50000000; The most per month. |
merchant_external_refs | array | Your own ids for the stores. |
days | 90 180 365 730 | A number of days, or the days of the week (0 = Sunday) for hours. |
valid_hours | integer | min 1; max 168; How many hours the link works. |
GET/v1/ach-authorizations
List signed ACH debit authorizations
| Parameter | In | Type | Notes |
|---|
customer_external_ref | query | string | Your own id for the customer. |
POST/v1/ach-authorizations/{id}/revoke
Revoke an ACH debit authorization
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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)
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
merchant_external_ref | query | string | Your 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 field | Type | Notes |
|---|
merchant_external_ref required | string | up to 200 chars; Your own id for the store. |
token required | string | up to 200 chars; A one-time token from your processor's bank account form. |
verification | network_check micro_transfers | How to verify it. |
POST/v1/bank-accounts/confirm
Confirm the two test deposit amounts
| Body field | Type | Notes |
|---|
merchant_external_ref required | string | up to 200 chars; Your own id for the store. |
verification_id required | string | up to 200 chars; The bank account check's id. |
amounts_cents required | array | The two small test deposit amounts, in cents, that confirm a bank account. |
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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
kind required | authorize charge capture void refund replace_hold | What kind it is. On an approval: authorize, capture, charge or refund. On a payment report: what happened. |
amount_cents required | integer | min 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).
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
amount_cents required | integer | min 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 required | string | up to 40 chars; The payment processor (stripe, square, braintree, adyen, paypal). |
processor_ref required | string | up to 200 chars; The payment's id at the processor (for example a Stripe PaymentIntent). |
status required | succeeded failed pending | Where it stands. On an incremental charge: pending, approved, declined, expired, cancelled. |
rail | card ach instant_bank rtp fednow cash other | How the money moves: card or ach. |
failure_reason | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
kind required | authorize charge capture void refund replace_hold | What kind it is. On an approval: authorize, capture, charge or refund. On a payment report: what happened. |
amount_cents required | integer | min 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 required | string | up to 40 chars; The payment processor (stripe, square, braintree, adyen, paypal). |
processor_ref required | string | up to 200 chars; The payment's id at the processor (for example a Stripe PaymentIntent). |
status required | succeeded failed pending | Where it stands. On an incremental charge: pending, approved, declined, expired, cancelled. |
approval_id | string | The id of the approval Wilby gave (the signed yes for a payment). |
incremental_charge_id | string | The incremental charge's id (top_…). |
failure_reason | string | up to 200 chars; Why it failed. |
rail | card ach instant_bank rtp fednow cash other | How the money moves: card or ach. |
paid_with | chatgpt_wallet | How it was paid (card, Google Pay, bank, agent token). |
agent_request | object | fields: signature_input, signature, signature_agent, authority, path; The agent's signed HTTP request (RFC 9421 message signature) that asked for the payment. |
payment_account_reference | string | up to 64 chars; The card network's Payment Account Reference (PAR), when your processor gives it. |
agent_payment | object | fields: paid_with, agent, reference; The payment as the agent platform made it (for agent-paid orders): how it was paid and its reference. |
customer_initiated | object | fields: 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)
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
status required | succeeded returned | Where it stands. On an incremental charge: pending, approved, declined, expired, cancelled. |
return_code | string | The bank's return code (for example R01). |
Disputes
Chargebacks and the signed evidence sent with them.
POST/v1/orders/{id}/disputes
Record a chargeback
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
reason required | overcharged not_delivered damaged other | Why, as a code or in words. On an incremental charge: the store's reason the customer sees. |
note | string | up to 500 chars; A note in plain words. |
GET/v1/disputes/{id}
Get a dispute and its evidence
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
POST/v1/disputes/{id}/resolve
Record how a dispute ended
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
outcome required | merchant_won customer_refunded | How it ended. |
refund_cents | integer | min 0; max 10000000000; An amount to refund, in cents. On a dispute: how much was refunded. |
note required | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
valid_days | integer | min 1; max 130; How many days the link works. |
return_url | string | up 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
| Parameter | In | Type | Notes |
|---|
from | query | string | Start date (YYYY-MM-DD) or start of the range. |
to | query | string | End date (YYYY-MM-DD) or end of the range. |
merchant_id | query | string | Wilby's id for the store (mer_…). |
tz | query | string | An IANA time zone, like America/New_York. |
GET/v1/analytics/daily
Day-by-day figures
| Parameter | In | Type | Notes |
|---|
from | query | string | Start date (YYYY-MM-DD) or start of the range. |
to | query | string | End date (YYYY-MM-DD) or end of the range. |
merchant_id | query | string | Wilby's id for the store (mer_…). |
tz | query | string | An IANA time zone, like America/New_York. |
GET/v1/analytics/stores
Figures per store
| Parameter | In | Type | Notes |
|---|
from | query | string | Start date (YYYY-MM-DD) or start of the range. |
to | query | string | End date (YYYY-MM-DD) or end of the range. |
merchant_id | query | string | Wilby's id for the store (mer_…). |
tz | query | string | An IANA time zone, like America/New_York. |
GET/v1/analytics/orders.csv
Export orders as CSV (no customer names or contact details)
| Parameter | In | Type | Notes |
|---|
from | query | string | Start date (YYYY-MM-DD) or start of the range. |
to | query | string | End date (YYYY-MM-DD) or end of the range. |
merchant_id | query | string | Wilby's id for the store (mer_…). |
tz | query | string | An IANA time zone, like America/New_York. |
POST/v1/analytics/dashboard-link
Make a private live-dashboard link (for one store or all)
| Body field | Type | Notes |
|---|
merchant_id | string | up to 40 chars; Wilby's id for the store (mer_…). |
valid_hours | integer | min 1; max 720; How many hours the link works. |
label | string | up to 80 chars; A short name shown to people. |
tz | string | up 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 field | Type | Notes |
|---|
staff_name required | string | up to 80 chars; The name of the person opening the Dashboard. |
staff_ref | string | up to 120 chars; Your id for that person. |
can_edit | boolean | Whether this dashboard link can change settings (or only view). |
merchant_id | string | up to 40 chars; Wilby's id for the store (mer_…). |
tz | string | up to 64 chars; An IANA time zone, like America/New_York. |
page | overview orders waiting assistants readiness listing setup | Which page to open. |
order_id | string | The order's id (prm_…). |
DELETE/v1/analytics/dashboard-link/{id}
Turn a dashboard link off
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
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 field | Type | Notes |
|---|
customer_external_ref required | string | up to 200 chars; Your own id for the customer. |
order_id | string | The order's id (prm_…). |
valid_minutes | integer | min 5; max 30; How many minutes it works. |
customer_contact | object | fields: 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)
| Parameter | In | Type | Notes |
|---|
limit | query | integer | How many to return (paging). |
GET/v1/client/orders/{id}
One order's screen-ready block (screen pass)
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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 field | Type | Notes |
|---|
preapproved_overage_pct required | integer | min 0; max 100; How far above the amount the customer lets you charge without asking (percent). |
approval_required_above_cents | integer or null | min 0; Above this amount, the customer approves each incremental charge themselves. |
app_return | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
app_return | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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)
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
ceremony_id required | string | up to 40 chars; The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing. |
response required | object | The 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)
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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)
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
code_id required | string | up to 40 chars; The id of a sent code. Send it back with the code the customer types. |
code required | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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 field | Type | Notes |
|---|
url required | string | up to 500 chars; An address. |
events | array | Webhook event types to send (order.*, incremental_charge.approved…), or * for all. |
description | string | up 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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
url | string | up to 500 chars; An address. |
events | array | Webhook event types to send (order.*, incremental_charge.approved…), or * for all. |
description | string | up to 200 chars; Plain text describing it. On an order: what was ordered. |
enabled | boolean | Whether it is turned on. |
DELETE/v1/webhook-endpoints/{id}
Remove a webhook endpoint
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
GET/v1/webhook-deliveries
List deliveries and their results
| Parameter | In | Type | Notes |
|---|
order_id | query | string | The order's id (prm_…). |
endpoint_id | query | string | A webhook endpoint's id. |
status | query | string: pending delivered failed cancelled | Where it stands. On an incremental charge: pending, approved, declined, expired, cancelled. |
limit | query | integer | How many to return (paging). |
POST/v1/webhook-deliveries/{id}/retry
Retry a delivery now
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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 field | Type | Notes |
|---|
name | string | up 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 field | Type | Notes |
|---|
path required | wilby_charges you_charge | Which 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.
| Parameter | In | Type | Notes |
|---|
to | query | string | End 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 field | Type | Notes |
|---|
format | ap2 vi acp | The format of the file or credential. |
user_public_jwk | object | Test tools: the customer device's public key (P-256 JWK). |
complete_request | string | up to 60000 chars; The full signed request the agent platform sent, for Wilby to check. |
agent_public_jwk | object | Test tools: the agent's public key (P-256 JWK) for a test credential. |
per_order_cents | integer | min 100; max 10000000000; The most per order. |
monthly_cents | integer | min 100; max 10000000000; The most per month. |
merchant_external_refs | array | Your own ids for the stores. |
days | integer | min 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 field | Type | Notes |
|---|
code required | string | up 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 field | Type | Notes |
|---|
store_id required | string | up to 40 chars; The store's id. |
description required | string | up to 300 chars; Plain text describing it. On an order: what was ordered. |
amount_cents required | integer | min 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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
GET/agent/v1/orders/{id}/proof
Proof the order stayed inside the permission
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
POST/agent/v1/orders/{id}/cancel
Cancel an order
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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 field | Type | Notes |
|---|
google_partner_id required | string | up to 100 chars; Your Google partner id. |
api_key required | string | up 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.
| Parameter | In | Type | Notes |
|---|
needs_attention | query | boolean | List 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 field | Type | Notes |
|---|
name | string | up to 60 chars; A name. |
redirect_uris required | array | The platform's return addresses for account linking (https). |
auth_method | client_secret_basic private_key_jwt | How the platform signs in to Wilby's account linking: client_secret_basic or private_key_jwt. |
jwks_uri | string | up to 500 chars; The https address where the platform publishes its public keys. |
GET/v1/ucp/link-clients
Platforms registered for account linking. Each with how many customers are linked through it now. Secrets are never shown.
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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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 field | Type | Notes |
|---|
request_id required | string | The sign-in request's id (oar_… or csi_…). |
customer_external_ref required | string | up to 200 chars; Your own id for the customer. |
payment_method_ref | string | up 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).
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |
| Body field | Type | Notes |
|---|
max_order_cents | integer or null | The most an AI agent may order at once from you. |
always_approval_required_above_cents | integer or null | Above this amount, the customer always approves the order themselves, whatever their limits. |
hours | object or null | When AI agents may order: tz (IANA time zone), days (0 = Sunday), start and end (HH:MM). |
blocked_agents | array | Refused 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.
| Parameter | In | Type | Notes |
|---|
store_ref | query | string | Your 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.
| Parameter | In | Type | Notes |
|---|
store_ref | query | string | Your id for the store. |
near | query | string | A 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 field | Type | Notes |
|---|
host required | string | up 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 field | Type | Notes |
|---|
name | string | up 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
days | query | integer | A 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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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 field | Type | Notes |
|---|
stage required | page checkout | Where the order is: created, confirmed, authorized, captured, cancelled, expired, disputed. |
method | string | up to 10 chars; The HTTP method of the signed request. |
host required | string | up to 300 chars; The website address where it happened. |
path required | string | up to 2000 chars; Which way to integrate, or a path. |
query | string | up to 2000 chars; The query string of the signed request. |
user_agent | string | up to 1000 chars; The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device. |
ip | string | up to 64 chars; The visitor's IP address (used only for the check, not kept in the record). |
bot_score | integer | min 1; max 99; Your bot tool's score for the visitor (1–99; below 30 means automated, as Cloudflare scores it). |
automated | boolean | Your own bot detection result: true when you think the visitor is automated. |
signature | string | up to 4000 chars; The signature. |
signature_input | string | up to 4000 chars; The Signature-Input header of the signed request. |
signature_agent | string | up to 500 chars; The Signature-Agent header (who the agent says it is). |
headers | object | The request headers that were signed. |
browser_signals | string | up 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". |
forwarded | string | up 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`)
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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=…
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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.
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby'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
| Parameter | In | Type | Notes |
|---|
id required | path | string | Wilby's id for it (a prefix plus 20 characters, like prm_… for an order). |