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 business | Path | What you build |
|---|---|---|
| Fixed prices (most businesses) | Either path below | Create 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 work | Wilby charges: save your own Stripe key once (see Your Own Stripe), or connect each store's Braintree, Square, Adyen or PayPal account | Create 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 it | You 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 on | Customers choose how much more may be charged without asking; above it they approve. See the Quickstart (Variable Amount After Checkout). |
| Orders placed by AI agents | AI Agents | Customers 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.
| When | Calls |
|---|---|
| Checkout | POST /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 answers | Webhook 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_by | Within 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 fails | Report 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 action | Ask first | Report |
|---|---|---|
| Hold at checkout (if you use holds) | approvals authorize | authorize |
| Charge at checkout (no hold) | approvals charge | charge |
| Charge the saved card more (any amount above what was held or paid) | incremental charges, then approvals charge once approved | charge |
| Capture the hold | approvals capture | capture |
| Release the hold and charge once for the estimate plus the approved extra | approvals replace_hold with the full amount | replace_hold with the full amount (one report) |
| Void the hold | Optional | void |
| Refund | approvals refund | refund |
| Tip, or something the customer added themselves (a return delivery) | No | charge 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 counter | No | charge 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
| Code | Meaning |
|---|---|
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
- Open
approval_urlin an in-app browser sheet (iOS:ASWebAuthenticationSession; Android: Custom Tabs). Sendreturn_urlwith your app's own link (for exampleyourapp://openhold-done), or set it once withPOST /v1/settings: after the customer answers, the page sends them there, which closes the sheet and tells your app it's done. No polling needed. - Decline is one tap on the page (no Face ID). If the customer declines in your own app, call
POST /v1/incremental-charges/{id}/decline. reason_titleis the bold line on the page (for example "Weighed 35 lb (estimated 25 lb)" or "One incremental charge hour of labor");notegoes under it;card_labelshows as "Charged To".- Every line on the pages can be your own:
POST /v1/settings {"wording": {"extra_lead": "…", "rules_choice": "Up to {pct}% more"}}. Keys:extra_title,extra_lead,extra_above_limit({limit}),rules_title,rules_lead,rules_choice({pct}),rules_choice_sub,rules_always_ask,rules_always_ask_sub.nullgoes back to the default. - Pages show your name, logo and colors from
POST /v1/settings.
Showing an Order (No Tables Needed)
GET /v1/orders/{id}returnsorder:status_labelandnext_stepin plain words (accept,take_payment,wait_for_customer,finish,none),money(estimate, up to without asking, paid, held, tip, refunded, final),waiting_extra, and every incremental charge with its title, note, card label and how it was decided. Every webhook carries the same block.- Each incremental charge has one status every screen can show as it is (your app, your web, the store, the customer):
customer_statusiswaiting,approved(not charged yet),approved_payment_failed,paid,declined,no_answerorwithdrawn, withstatus_labelin plain words. Show these instead of working the status out from your own tables, so every screen agrees. - "My Orders":
GET /v1/orders?customer_external_ref=…(alsomerchant_external_ref,stage,limit,before). - Send an approval link again:
POST /v1/incremental-charges/{id}/link. Earlier links stop working, so only one is live. - Extra-charge reasons:
extra_parts,extra_labor,substitution,price_change,over_estimate,add_on,special_handling,damage_fee,other. Your own line goes inreason_title.
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.
- Once:
POST /v1/settings {"screen_origins": ["https://www.example.com"]}(the websites where the screens run). - For each page view, your server asks for a screen pass for that customer:
POST /v1/screen-sessions {"customer_external_ref": "cust_42"}(addorder_idto limit it to one order). It lasts up to 30 minutes. Putclient_secreton the page; never your API key. - Add the script and the tags you need:
Or set the pass once for every tag:<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 -->Wilby.init({clientSecret: "wcs_…"}). - 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).
- A stricter rule (or the same) saves at once, recorded as confirmed on your website. Declining an incremental charge and turning an agent off take effect at once.
- Approving an incremental charge, or a looser rule, opens a small Wilby window where the customer confirms it's them (their phone's lock, or a one-time code). It closes by itself and the screen updates. A passkey belongs to the website it was made on, so this step always runs on Wilby's own page.
- Your page's Content-Security-Policy needs
script-src https://app.usewilby.comandconnect-src https://app.usewilby.com. - The Maple & Pine sample uses these screens: see it working (sandbox servers only).
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.
WilbyLimitPicker,WilbyOrderCard,WilbyApproveExtra,WilbyPaymentSettings, each with aWilby(baseUrl, clientSecret, appReturn).- If your app is registered (
appsinPOST /v1/settings), approving uses the phone's own Face ID sheet through/v1/client/incremental-charges/{id}/passkey/*. Otherwise Wilby's page opens in an in-app browser sheet and comes back to yourappReturnlink (yourapp://…) when the customer is done.
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).
createWilby({baseUrl, clientSecret, appReturn, browser, passkeys?}), then<WilbyLimitPicker>,<WilbyOrderCard>,<WilbyApproveExtra>,<WilbyPaymentSettings>.browser: the in-app browser sheet (react-native-inappbrowser-reborn, or expo-web-browser in Expo apps).passkeys(optional, apps registered with Wilby): react-native-passkey, for the phone's own Face ID sheet.
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.
- You text the code when your webhook takes
customer.code_requested: send itsmessageto the customer's phone. - Wilby emails the code when you don't text codes and you gave the customer's email:
POST /v1/customers/{ref}/contact {"email": "…"}(orcustomer_contacton an incremental charge or a screen pass). Kept 7 days, then deleted. In the sandbox, codes to example.com addresses are kept, not sent:GET /v1/sandbox/emails. - First setup: before a customer's first passkey is made, a code proves it's them (so holding the link alone isn't enough). Turn it off with
first_setup_code: falseonly if you can't send codes yet. - The record always says how the customer confirmed: passkey, or a code (texted by you, or emailed by Wilby), with a masked address.
- The passkey is saved on the phone as "Your [Business] Account", or "[Business] · Jane D." if you send
labelincustomer_contact. Never your customer number.
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.
- Put an Open Wilby button in your admin. When it's clicked, your server calls
POST /v1/dashboard/open {"staff_name": "Ana Lopez", "can_edit": true}and sends the person tourl. The link works once, for 15 minutes, and opens a session of 8 hours. Optional:staff_ref(your id for the person),merchant_id(one store only, view only),page(orders,waiting,agents) ororder_id(open one order). - With
can_edit, the person may change which agents may order; each change is signed under their name. Leave it out for view only. Nothing on these screens moves money. - Show it inside your own dashboard:
POST /v1/settings {"embed_origins": ["https://admin.example.com"]}(up to 5). Otherwise the pages refuse to be framed. - A longer view-only link to share (for example with a store owner):
POST /v1/analytics/dashboard-link.
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).
- Stores under your Stripe platform (Connect): create each store with
processor: "stripe"and its connected account id (acct_…) asprocessor_account_ref. - One Stripe account for everything: use
processor_account_ref: "self". - Card holds, incremental charges, refunds and disputes then run on your Stripe; Wilby checks your accounts for disputes every 30 minutes and answers them from the signed record.
- Save customers' cards on your Stripe as usual and send them as
payment_method_ref(pm_…, orcus_…:pm_…for a saved card). Changed card:POST /v1/customers/{ref}/payment-method.
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.
- Adyen: an API credential with the Checkout and Disputes roles, the merchant account, and a Standard webhook to
https://app.usewilby.com/webhooks/adyenwith an HMAC key. Saved cards are sent aspayment_method_ref"<shopperReference>:<storedPaymentMethodId>". Holds use manual capture; charges the customer didn't make in the moment are marked as stored-card payments. Captures, cancels and refunds are confirmed by Adyen's webhook; disputes arrive the same way and are answered from the signed record as a PDF. An authorisation Adyen confirms later for an order without a matching record is reversed. - PayPal: the client ID and secret of the store's PayPal app (Developer Dashboard › Apps & Credentials); Wilby adds its webhook to
https://app.usewilby.com/webhooks/paypalto the app itself. Cards and PayPal wallets are saved by your own checkout with PayPal's JavaScript SDK (save payment methods); send the saved payment token id aspayment_method_ref. Holds are PayPal authorizations (valid 29 days; the first 3 days are PayPal's honor period), captured once as the final capture, and the rest released. Charges the customer didn't make in the moment are marked as stored-credential payments. A hold PayPal answers as pending is voided at once and the order treated as not paid. Disputes arrive by webhook and are answered from the signed record as a PDF; PayPal has no draft step, so evidence is sent only when every check passes, otherwise the dispute waits for a person in PayPal. - Braintree and Square: Wilby checks their disputes every 30 minutes and answers them from the signed record.
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.
- 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-associationand/.well-known/assetlinks.jsonfor your app. - iOS: add the Associated Domains entitlement
webcredentials:app.usewilby.com. Android: nothing else (Credential Manager reads assetlinks.json). - When the customer taps Approve: your server calls
POST /v1/incremental-charges/{id}/passkey/beginand handsoptionsto the app. The app calls the platform passkey API (iOSASAuthorizationPlatformPublicKeyCredentialProviderwithrp_id; Android Credential ManagerGetPublicKeyCredentialOption; Flutter: a passkeys package), then your server sends the result to/passkey/finish. - If
kindisregister(first time on this account), create the passkey withoptions, finish, then callbeginagain 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. - 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/finishanswersinvalid_response(notpasskey_failed). Test once: a known-good answer must succeed. - New phone: if
kindisauthenticatebut 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. Whennew_phone_availableis true, offer "New Phone? Set Up Face ID Here": callPOST /v1/incremental-charges/{id}/passkey/new_phone/send(a code goes to your system ascustomer.code_requested; text it to the customer), thenPOST /v1/incremental-charges/{id}/passkey/new_phone/verifywithcode_idand the code. That returns aregisterprompt: create the passkey, send it to/passkey/finish, thenbeginagain 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
- Your order id →
order_id(so the store screen can find the order). Create the order right after the order is saved, before slow work like texts, emails and pushes, so the store never opens an order before it's linked. - Each incremental charge the store asked for:
incremental_charge_id, amount, which card to charge, status. The customer may answer hours later, by webhook, with nobody signed in. - Webhook event ids you've handled, so a resent webhook never charges twice.
- If you charge again later: at checkout, the saved card you will charge (every channel that creates orders: web, app, phone).
- Not needed: card numbers, the customer's rules, the signed record (Wilby keeps those).
Good to Know
- All times in the API are UTC. Show your store its own time zone.
- Default order expiry is 14 days. Work that takes longer (cleaning, repairs, made-to-order): send
expires_at(up to 120 days). - If you use card holds: they lapse after about 7 days. Wilby sends
authorization.expiring_soonon day 6 with what to do. - Every POST needs an
Idempotency-Key; use one per action, never per attempt. - If Wilby can't be reached when a store charges an incremental charge, don't charge it. Retry, and tell the store it's waiting.