Address validation & geocoding for SCAYLE.
React widgets for the storefront plus a Node handler implementing SCAYLE's first-class address-check gateway protocol. Drops straight into the merchant's Custom Address Validation Provider slot in SCAYLE Panel — replacing the built-in Google Maps Autocomplete option. MIT licence.
Two packages, not one
Storefront widget + server-side gateway.
@acuris-geo/scayle-checkout
React widgets for the storefront
<AcurisAddressInput> typeahead and
<AcurisAddressValidator> render-prop, emitting
SCAYLE BaseAddress-shaped objects (nested
country.iso2Code, zipCode, split
street / houseNumber). Works under
Nuxt-first SCAYLE storefronts and Next.js BFFs.
@acuris-geo/scayle-gateway
Address-check gateway handler
A Node handler implementing SCAYLE's third-party
address-check gateway HTTP contract. SCAYLE POSTs every
shipping/billing address change here during checkout; the handler
returns 200 (exact match), 200 +
suggestions (corrections shown in SCAYLE's native overlay),
422 (unsupported), or 503 (transient).
Quick start
Install. Wire. Done.
What it does
Drop-in pieces.
SCAYLE BaseAddress shape
Nested country.iso2Code object, zipCode /
houseNumber / firstName / lastName
— exactly the type from @scayle/checkout-types. Hand it
straight to the Checkout API's PUT /api/co/v3/state/order/addresses/{type}.
Native SCAYLE gateway protocol
The handler implements the documented HTTP contract verbatim — no adaptation layer needed in SCAYLE Panel. Configure URL + Basic Auth in Panel → Checkout → Address Validation → Custom Provider.
Suggestion overlay support
When Acuris returns a corrected match below
exactConfidence, the gateway responds with a
suggestions[] array and SCAYLE renders its native
correction overlay. No widget required.
Multi-runtime adapters
buildLambdaHandler for AWS Lambda,
buildNodeHttpHandler for Express / raw Node http,
buildGatewayHandler for generic async runtimes.
Same processAddressCheck core under each.
HTTP Basic Auth
SCAYLE's recommended posture for gateway endpoints. The Lambda
and Node http adapters check the
Authorization: Basic … header and reject 401
for mismatched credentials.
Replaces Google Maps Autocomplete
SCAYLE has been actively steering merchants away from Google for B2B + Packstation cases (release notes 2.1.83). Acuris ships the 240+ country coverage Google doesn't have outside its primary markets.
Architecture
Three pieces, two trust boundaries.
Browser Your backend Acuris
───────── ───────── ─────────
<AcurisAddressInput> ──► /api/acuris/suggest ──► GET /suggest
<AcurisAddressValidator> ─► /api/acuris/validate ──► POST /validate
(acuris-av-sdk + (api.acuris-geo.com)
ACURIS_API_KEY +
iso2ToIso3)
SCAYLE Checkout Acuris
───────────── ──────
on every shipping/billing
address change ──► your-lambda/url ──► POST /validate
(acuris-scayle-gateway + POST /suggest
Basic Auth)
The storefront component is optional polish; the gateway is the canonical SCAYLE integration point. Most merchants ship both — the widget gives a Smarty-style typeahead UX on the form; the gateway guarantees every backend and partner-code address goes through Acuris. Full details in the architecture doc and integration guide.
Why pick Acuris over the built-in options
SCAYLE address-validation provider comparison.
| Property | Acuris | Google Maps Autocomplete | SCAYLE built-in regex |
|---|---|---|---|
| Country coverage | 240+ | ~70 (primary markets) | Format-only, no semantic check |
| House-number validation | Yes | Partial | No |
| Postcode / city consistency check | Yes | Yes | No |
| B2B / Packstation handling | Yes | No (SCAYLE flagged this gap) | No |
| EU data residency | Yes (German GmbH) | US-default | n/a |
| EUDI Wallet support | Yes (live verifier) | No | No |
See it run
A working Next.js storefront, deployed.
Running SCAYLE?
The connector is open-source under MIT — clone and run today. Acuris API keys come with a free Dev bundle: 1,000 address validations and 1,000 geocoding lookups (plus email and phone validation credits), valid for 4 weeks.