Wilby DocsGet Sandbox Keys

Platform Integration

How to put Wilby in front of your payments. Pick the path that matches your business; you only build the parts you use.

Pick Your Path

Your businessPathWhat you build
Fixed prices (most businesses)Either path belowCreate the order at its price, take the payment, finish it. No incremental charges and no customer limits on the price. See the Quickstart (Fixed Price).
You want the least workWilby charges: save your own Stripe key once (see Your Own Stripe), or connect each store's Braintree, Square, Adyen or PayPal accountCreate the order and finish it. Wilby takes the payment (hold or charge); if the price can change, it asks the customer above their limit and charges the incremental charge. See the Quickstart.
You already call your processor and want to keep doing itYou charge (Platform-Run Payments)Ask Wilby before each money step, then report what you did. This guide, from "The Flow" on.
The final price can change after checkout (services, weighed goods, substitutions)Either path, with variable_amount onCustomers choose how much more may be charged without asking; above it they approve. See the Quickstart (Variable Amount After Checkout).
Orders placed by AI agentsAI AgentsCustomers connect an agent and set its limits; the agent orders through Wilby's tools or presents a signed mandate (AP2, Verifiable Intent). Above the limits, the customer approves. See AI Agents.

Paths mix: a platform can take app orders on one path and agent orders on another. Words, colors and choices on the customer pages are yours (POST /v1/settings: branding, wording, rule_choices_pct).

The Flow (You Charge)

Shown with a hold at checkout and a price that can go up after the work is done. Without a hold, charge at checkout and skip what doesn't apply.

WhenCalls
CheckoutPOST /v1/orders (leave out max_amount_cents to use the customer's own rule; send display_ref, the order number they know) → /accept → /approvals {kind:"authorize"} → your hold → /payments {kind:"authorize"}
Price goes up/incremental charges/preview (optional, for your store screen) → /incremental charges. approved: charge it. pending_customer: send the customer approval_url and wait for the webhook
Customer answersWebhook incremental_charge.approved → /approvals {kind:"charge"} → charge → /payments {kind:"charge", incremental_charge_id}. incremental_charge.declined / incremental_charge.cancelled: charge nothing
No answer by answer_byWithin about a minute Wilby marks the incremental charge expired and sends incremental_charge.expired (the incremental charge shows "No Answer"). Charge nothing; the order goes back to where it was, so you can finish it or ask again. Approvals after answer_by are always refused (request_expired).
Approved, but your charge failsReport it: /payments {kind:"charge", status:"failed", incremental_charge_id, failure_reason:"Card declined: …"}. The incremental charge shows "Approved, Payment Failed" and incremental_charge.charge_failed is sent. The approval stays valid: charge another saved card or send a payment link, then report that charge with the same incremental_charge_id (it shows "Approved and Paid").
Finished/settle {capture_cents} → do exactly what partner_must says → report it

What to Report for Each Store Action

Store actionAsk firstReport
Hold at checkout (if you use holds)approvals authorizeauthorize
Charge at checkout (no hold)approvals chargecharge
Charge the saved card more (any amount above what was held or paid)incremental charges, then approvals charge once approvedcharge
Capture the holdapprovals capturecapture
Release the hold and charge once for the estimate plus the approved extraapprovals replace_hold with the full amountreplace_hold with the full amount (one report)
Void the holdOptionalvoid
Refundapprovals refundrefund
Tip, or something the customer added themselves (a return delivery)Nocharge with customer_initiated {purpose:"tip"|"add_on"}: outside the order's price, never counts toward their limit
A payment link the customer paid, or a card reader / cash at the counterNocharge with customer_initiated {purpose:"payment_link"|"other"} (and rail): pays the order itself, recorded as paid by the customer. Without customer_initiated it is recorded as not approved through Wilby.

Older pattern, still accepted: one card charge reported as two parts with the same processor_ref, capture (estimate) + charge (extra), only while the hold is still on record. Prefer replace_hold.

Reporting the Rest of the Order

Report every capture, void, refund and cancel on the order, not only incremental charges. The simplest reliable way: read GET /v1/orders/{id} first and send only what isn't there yet (compare held_cents, captured_cents, refunded_cents and the payments list with your own). A refund your system splits across two charges is two refund reports.

Idempotency: a key's first answer is always replayed, errors included. If you retry a call after fixing what made it fail (for example after withdrawing a pending extra), use a new key.

Answers You Get Back

Approval (POST /approvals):

{"object":"approval","approval_id":"evt_…","order_id":"prm_…","kind":"charge","amount_cents":1750,
 "allowed":true,"reason":"approved_incremental_charge","valid_until":"2026-11-12T15:10:00.000Z",
 "card_indicators":{…},"proof":{"hash":"…","signature":"…","key_id":"…","chain_index":7}}

A yes is valid for 10 minutes and can be used for one report. A retry with the same Idempotency-Key returns the same answer. reason when no: no_approved_incremental_charge, above_approved_incremental_charge, above_estimate, above_hold, above_final, no_hold, above_captured, not_awaiting_funding, order_expired, promise_<stage>.

Payment report (POST /payments): {"object":"payment_report","payment_id":"pay_…","approved":true,"approval_problem":null,"order":{…}}. A payment without a valid approval is still recorded (it happened) with approved:false and the problem.

Extra (POST /incremental charges): {"incremental charge":{"incremental_charge_id":"top_…","status":"approved"},"order":{…}} or {"incremental charge":{"incremental_charge_id":"top_…","status":"pending_customer","approval_url":"https://…","answer_by":"…"},"order":{…}}.

Preview (POST /incremental charges/preview): {"decision":"needs_approval","rule":"above_max_amount","new_total_cents":6125,"max_amount_cents":5250,"room_cents":875,…}.

Order (GET /v1/orders/{id}): {"order":{…},"incremental charges":[…],"payments":[…],"evidence":[…],"disputes":[…],"history":[…]}. The order itself is under order.

Settle (platform-run): the order.captured record says partner_must, for example {"action":"capture","amount_cents":4375}, or a list (capture, then refund).

Errors You Should Handle

CodeMeaning
incremental_charge_pending (409)An incremental charge is already waiting for the customer. Withdraw it with POST /v1/incremental-charges/{id}/cancel, or wait.
awaiting_customer (409)Settle while the customer hasn't answered yet.
incremental_charge_required (409)The final price is above what was paid: ask for an incremental charge first.
duplicate_report (409)This payment was already reported (safe to ignore on a retry).
report_inconsistent (422)The report breaks the money rules (capture above the hold, refund above what was captured).
already_decided / not_pending / request_expired (409)The customer (or the store) already answered, or time ran out.
processor_no_answer (503)The payment processor hasn't confirmed the payment yet. Nothing was recorded. Try again in a minute: it is safe, because Wilby looks for that payment first and never sends it twice.
already_paid (409)The store tried to withdraw an incremental charge that was already paid. Refund it instead.
incremental_charge_not_payable (409)The incremental_charge_id on a payment report isn't an approved, unpaid extra (or is smaller than the charge).
passkey_failed (400)The customer cancelled, used another passkey, or the signature didn't check out. Let them try again, then fall back to the page.
invalid_response (400)The phone's answer couldn't be read at all (not WebAuthn JSON, or a field isn't base64url). This is an integration bug, not the customer: see "Approve Inside Your App".
merchant_not_found, evidence_required, invalid_return_url (422)Fix the request.

Customer Pages and Your App

Showing an Order (No Tables Needed)

Ready-Made Screens (Your Website)

Instead of building the customer screens yourself, add Wilby's. They take your name, colors and wording, and nothing on them can charge a card.

  1. Once: POST /v1/settings {"screen_origins": ["https://www.example.com"]} (the websites where the screens run).
  2. For each page view, your server asks for a screen pass for that customer: POST /v1/screen-sessions {"customer_external_ref": "cust_42"} (add order_id to limit it to one order). It lasts up to 30 minutes. Put client_secret on the page; never your API key.
  3. Add the script and the tags you need:
    <script src="https://app.usewilby.com/kit/v1/wilby.js"></script>
    <wilby-limit-picker client-secret="wcs_…" amount-cents="5000"></wilby-limit-picker>   <!-- checkout -->
    <wilby-order-card client-secret="wcs_…" order-id="prm_…"></wilby-order-card>           <!-- an order -->
    <wilby-approve-extra client-secret="wcs_…" order-id="prm_…"></wilby-approve-extra>     <!-- just what's waiting -->
    <wilby-payment-settings client-secret="wcs_…"></wilby-payment-settings>              <!-- account page -->
    Or set the pass once for every tag: Wilby.init({clientSecret: "wcs_…"}).
  4. Listen for what happened: wilby:rule-saved, wilby:extra-approved, wilby:extra-declined, wilby:agent-off, wilby:error (each bubbles out of the tag with details).

In Your Flutter App

The same four screens as Flutter widgets: download wilby_flutter 2.0.0 (Flutter 3.41 or newer; the README inside has the setup). Your server gets the screen pass the same way; apps send no Origin, so the pass works from your app.

In Your React Native App

The same four screens as React Native components (bare or Expo): download wilby-react-native 2.0.0, then npm install ./wilby-react-native-2.0.0.tgz (React Native 0.74 or newer; the README inside has the setup).

When the Customer Can't Use a Passkey

A passkey uses whatever unlocks the device: Face ID, a checkpoint, a passcode or pattern on a phone; Windows Hello, Touch ID or the password on a computer (or the customer's phone, by QR code). A device with no screen lock can't make one, so the customer gets a one-time code instead.

Dashboard (Open Wilby From Your Admin)

One place for your team: the numbers, every order with its signed record, what's waiting on customers, orders from AI agents (by agent, and how often a customer said one got it wrong), agents turned away, reported mistakes, and which agents may order. Wilby hosts the screens; your team signs in with your own login, not ours.

Your Own Stripe

If Wilby charges for you and your stores are on your own Stripe, save a restricted key once: POST /v1/settings/stripe-key {"stripe_key": "rk_test_…"}. It is checked with Stripe, sealed, and never shown again (GET /v1/settings shows only its kind and last 4). Permissions it needs: PaymentIntents: Write, PaymentMethods: Read, Customers: Read, Refunds: Write, Disputes: Write, Charges: Read (and Connect: Read/Write if stores are connected accounts).

Each Store's Own Braintree, Square, Adyen or PayPal Account

Create the store with processor: "braintree", "square", "adyen" or "paypal", then POST /v1/merchants/{ref}/connect-link and send the link to the store owner. Square: the owner approves on Square. Braintree, Adyen and PayPal: the owner enters the store's own keys on a one-time Wilby page; they are checked with the processor, sealed, and never shown again.

Approve on Your Own Website (No Window)

Add your website to screen_origins (POST /v1/settings). Wilby then lists it in https://app.usewilby.com/.well-known/webauthn, so Chrome, Edge and Safari let your page show the Face ID / fingerprint prompt for Wilby's passkey itself. The web script (<wilby-approve-extra>) does it for you: the customer taps Review and Approve and confirms on your page. The signature covers this exact incremental charge and amount, and Wilby checks the answer came from your listed website. Browsers read at most 5 site names from that list; GET /v1/settings shows yours under passkey_websites (in_page or wilby_window). Other browsers, and a customer who hasn't set up a passkey yet, use the small Wilby window as before.

Approve Inside Your App (Optional)

Instead of opening the approval page, your app can show the phone's own Face ID / fingerprint sheet. The customer uses the same passkey as on Wilby's pages, and the signature covers this exact extra and amount.

  1. Once: POST /v1/settings {"apps": {"ios": ["TEAMID.com.example.app"], "android": [{"package_name": "com.example.app", "sha256_cert_fingerprints": ["AB:CD:…"]}]}}. Use the Play App Signing certificate and, for test builds, the upload certificate. Wilby then publishes /.well-known/apple-app-site-association and /.well-known/assetlinks.json for your app.
  2. iOS: add the Associated Domains entitlement webcredentials:app.usewilby.com. Android: nothing else (Credential Manager reads assetlinks.json).
  3. When the customer taps Approve: your server calls POST /v1/incremental-charges/{id}/passkey/begin and hands options to the app. The app calls the platform passkey API (iOS ASAuthorizationPlatformPublicKeyCredentialProvider with rp_id; Android Credential Manager GetPublicKeyCredentialOption; Flutter: a passkeys package), then your server sends the result to /passkey/finish.
  4. If kind is register (first time on this account), create the passkey with options, finish, then call begin again to approve. The first time is two prompts: setting up Face ID only creates the key, and the second prompt signs the approval of this exact amount, which is what holds up in a dispute. Suggested wording: "First time: set up Face ID, then confirm." Every later approval is one prompt.
  5. Pass the phone's answer through byte for byte. Many server frameworks change request input (for example adding backslashes before quotes). Send the JSON exactly as the phone produced it; if it can't be read, /passkey/finish answers invalid_response (not passkey_failed). Test once: a known-good answer must succeed.
  6. New phone: if kind is authenticate but the phone has no passkey for this account (iOS shows a QR code, Android finds none), the customer set up Face ID on another phone. When new_phone_available is true, offer "New Phone? Set Up Face ID Here": call POST /v1/incremental-charges/{id}/passkey/new_phone/send (a code goes to your system as customer.code_requested; text it to the customer), then POST /v1/incremental-charges/{id}/passkey/new_phone/verify with code_id and the code. That returns a register prompt: create the passkey, send it to /passkey/finish, then begin again to approve. The old phone keeps working. Without a code, holding the order is not enough to add a phone.

Declining needs no Face ID: use POST /v1/incremental-charges/{id}/decline. The approval page and text link keep working for customers outside your app.

What to Keep on Your Side

Good to Know