Wilby DocsGet Sandbox Keys

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.

"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). Start the charge as soon as your server sees 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

OptionWhat it does
incrementalChargeIdRequired. The incremental charge to approve (top_…).
sendRequired. 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.
fallbackUrlWilby's approval page (approval_url), for browsers that can't use Wilby's passkey on your site.
openFallbackSet false to get fell_back without the helper opening fallbackUrl itself.
themeYour colors and shapes: accent, accentText, background, text, link, border, font, radius, buttonRadius.
wordsYour own wording for any line (keys below). {lock} is the device's lock name (Face ID, Touch ID, fingerprint, Windows Hello), {device} the device.
mountAn 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)

StatusWhat it means
approvedThe customer said yes. Not that money moved: show a charging state until your charge has had its chance.
cancelledThe customer closed it. Nothing changed; they can try again.
fell_backThis browser can't use Wilby's passkey on your site (Safari before 18, Firefox): open url (Wilby's page).
already_answeredThe charge was already answered (or withdrawn).
expiredThe charge expired before the customer answered.

What the Customer Sees, in Order

  1. Face ID, Touch ID or a fingerprint with a passkey this device can reach.
  2. 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).
  3. A device that can't hold a passkey, or a set-up that fails: "Approve With a Code".
  4. Using another device (QR code) is always the smaller choice.
  5. 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)

StepRouteNotes
StartPOST /v1/incremental-charges/{id}/passkey/beginSend 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.
FinishPOST /v1/incremental-charges/{id}/passkey/finishPass the device's answer unchanged as response, with ceremony_id. done: true means approved.
Set up this devicePOST …/passkey/new_phone/send, then …/new_phone/verifyA texted code proves it's the customer, then this device's passkey is set up and used.
Approve with a codePOST …/code/send, then …/code/verifyFor devices that can't hold a passkey. Recorded as one_time_code.
Report what happenedPOST …/passkey/reportClosed prompts and errors, for the Approvals by Device report.
See resultsGET /v1/approval-attemptsApprovals 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.