Approve on Your Own Screens
Let customers approve an incremental charge on your website or in your app, with Face ID, Touch ID, a fingerprint or a texted code, without leaving your page.
done: true.The Helper (Websites)
<script src="https://app.usewilby.com/kit/v1/approve.js"></script>
const r = await Wilby.approve({
incrementalChargeId: 'top_…',
send: (body) => fetch('/your-server/wilby-step', { method: 'POST', headers: { 'content-type': 'application/json' },
body: JSON.stringify(body) }).then((x) => x.json()),
fallbackUrl: approvalUrl,
});
Your server forwards body unchanged to POST /v1/incremental-charges/{id}/approval-step with your API key (only for the signed-in customer's own charge) and returns Wilby's answer, errors included. Your API key never reaches the browser. Your website must be in screen_origins (see Settings).
Options
| Option | What it does |
|---|---|
incrementalChargeId | Required. The incremental charge to approve (top_…). |
send | Required. A function that posts the helper's body to your server and returns Wilby's answer as JSON. Your server forwards it unchanged to POST /v1/incremental-charges/{id}/approval-step with your API key, for the signed-in customer's own charge only. |
fallbackUrl | Wilby's approval page (approval_url), for browsers that can't use Wilby's passkey on your site. |
openFallback | Set false to get fell_back without the helper opening fallbackUrl itself. |
theme | Your colors and shapes: accent, accentText, background, text, link, border, font, radius, buttonRadius. |
words | Your own wording for any line (keys below). {lock} is the device's lock name (Face ID, Touch ID, fingerprint, Windows Hello), {device} the device. |
mount | An element to show the box in, instead of a centered overlay. |
Wording Keys (words)
elsewhere, failed, setup_failed_code, setup_how, code_how, setup_button, code_button, retry_button, other_phone, other_computer, code_label, code_confirm, code_resend, code_resent, setup_failed, close. Each replaces one line; {lock}, {device} and {device_lower} are filled in.
Results (r.status)
| Status | What it means |
|---|---|
approved | The customer said yes. Not that money moved: show a charging state until your charge has had its chance. |
cancelled | The customer closed it. Nothing changed; they can try again. |
fell_back | This browser can't use Wilby's passkey on your site (Safari before 18, Firefox): open url (Wilby's page). |
already_answered | The charge was already answered (or withdrawn). |
expired | The charge expired before the customer answered. |
What the Customer Sees, in Order
- Face ID, Touch ID or a fingerprint with a passkey this device can reach.
- If the passkey is on another device, or the prompt was closed or found nothing: "Try {lock} Again" first (after one close), then "Set Up {lock} on This {device}" (a texted code, then this device's lock).
- A device that can't hold a passkey, or a set-up that fails: "Approve With a Code".
- Using another device (QR code) is always the smaller choice.
- Browsers that can't use Wilby's passkey on your site (Safari before 18, Firefox):
fell_back, open Wilby's page.
Building It Yourself (Apps or Your Own Screens)
| Step | Route | Notes |
|---|---|---|
| Start | POST /v1/incremental-charges/{id}/passkey/begin | Send user_agent. The answer has options for the browser or phone, device {kind, lock, name}, likely_on_another_device, new_phone_available, code_approval_available. |
| Finish | POST /v1/incremental-charges/{id}/passkey/finish | Pass the device's answer unchanged as response, with ceremony_id. done: true means approved. |
| Set up this device | POST …/passkey/new_phone/send, then …/new_phone/verify | A texted code proves it's the customer, then this device's passkey is set up and used. |
| Approve with a code | POST …/code/send, then …/code/verify | For devices that can't hold a passkey. Recorded as one_time_code. |
| Report what happened | POST …/passkey/report | Closed prompts and errors, for the Approvals by Device report. |
| See results | GET /v1/approval-attempts | Approvals by device and what went wrong. |
Errors to handle: passkey_failed (let them try again), wrong_code, code_expired, too_many_attempts, not_pending (already answered), request_expired. See Error Codes.