How to integrate a custom Address Check Provider

Introduction

The address validation feature can be used to validate customer's billing and/or shipping address during the checkout flow. With the proper configuration, you can make sure that the important information is being filled correctly, with minimal friction in the checkout flow. The purpose of this tutorial is to cover the integration of a custom Address Check Provider.

How it works

Address check integration in SCAYLE follows a simple gateway pattern. When fully set up, SCAYLE’s checkout invokes an endpoint exposed by the address check gateway provided by you whenever a customer adds or makes a change to his or her shipping or billing address.

Your gateway is expected to implement an interface that can receive address check requests from checkout and respond accordingly. When receiving address check requests from checkout, your gateway is then expected to translate the checkout requests to the external source - your address check provider - and back.

The Generic API

As outlined above, your Address Check Gateway is expected to implement a generic interface for address check requests and responses.

Reference Architecture

See the diagram below for a reference archictecture, with your Gateway handling the communication between SCAYLE Checkout and your Address Check Provider.

The following sections explore the required interfaces in detail.

Request

When a change is made to an existing address or a new address is created, the following JSON payload is sent as a POST request to your Address Check Gateway.

Note that the following fields are optional. Whether these optional fields are provided in the Address Check Request is determined by your checkout configuration.

• additional
• addressCode
• county
• firstName
• lastName
• houseNumber
• zipCode

Response

After performing the Address Check in your address check provider, your gateway is expected to respond to the Address Check Request following a specific schema.

The SCAYLE checkout can process the following cases.

Exact Match or No Match

This is the case when the address provided by your customer (the address sent to your gateway) is considered accurate or there were no matching addresses found by your address check provider.

To respond with an exact match, respond to the address check request as follows.

This response results in checkout accepting the entered delivery address. The customer proceeds to the next step

Alternatives Available

This is the case when the address provided by your customer (the address sent to your gateway) is considered not accurate by your address check provider and there are alternatives available.

To respond with a list of alternatives, respond to the address check request as follows.

This response results in checkout opening an address selection overlay. The customer sees a list of address suggestions and needs to select one to proceed to the next step.

Response Codes

Your Address Check Gateway may respond with the following response codes.

Configuration

Address checks are configured on two layers within the application. The system-to-system integration itself (see section “Endpoint”) and the behaviour in checkout (see section “Checkout”).

Endpoint

Please refer to address validation on how to configure the integration of your endpoint.

These configuration properties can be provided via the Checkout Configuration API. Reach out to your SCAYLE Account Manager with any questions.

Checkout

After setting up the integration with the Address Check Gateway, the feature can be enabled and customized for the Checkout process.

Please refer to address validation on how to configure checkout.

These configuration properties are set via the Generic Checkout Configuration in the SCAYLE Panel.

Best Practices

Caching

Depending on the amount of address check requests and the amount of potential cache hits, you may reduce the amount of API calls reaching your address check provider by caching address checks. Since address checks are always synchronous, this can significantly improve the speed of address checks.

Authentication & Authorization

To protect your Address Check Gateway and your Address Check Provider from unauthenticated access, you may protect the API endpoints using Basic Authentication.

Resiliency

As address checks are conducted synchronously within the customer’s checkout process, consider implementing your Address Check Gateway using fault-tolerant patterns so that a potential downtime of your Address Check Provider does not negatively influence the customer’s checkout experience. A common pattern to deal with such cases is the implementation of a circuit breaker that closes as soon as the failure rate of your Address Check Provider has reached a certain threshold.

In such cases, consider responding to the Address Check Request with a fallback response that corresponds to the case Exact Match or No Match.