Using Intelligent Addressing with a Custom Address Lookup Component

PayBridge provides functionality for prefilling address fields in the payment provider with an address provided by the customer on your form. There are two supported ways of getting the address from the form.

• As individual address fields

  This is most useful is you collect customer address details using separate questions, e.g.

  • House Number
  • Street
  • Town
  • Postcode

  If you choose to pass address data from your form using this method, set Include Address to 'From individual fields'. PayBridge will display the address fields that you payment provider accepts, and you can map individual questions to each field.

• From an address lookup

  The most common approach to collecting addresses is to use one of Jadu Central's postcode lookup integrated components. Jadu Central provides lookup components for a number of third party address services, such as SinglePoint as ESRI LocatorHub.

  If you choose to pass address data from your form using this method, set Include Address to 'From address lookup'. PayBridge will ask you to map in the UPRN field (or property_identifier) from your postcode lookup question.

note

Some payment adapters do not currently support intelligent addressing. If you do not see Include Address when configuring PayBridge mappings on your form, speak to Jadu Support.

Working with custom address lookups

Internally PayBridge uses this UPRN field to determine the address service used. It then gives the UPRN to the address service, and receives back the full set of data for the property. This data differs in format between address services, so each postcode lookup component in Jadu Central defines a hydrator, which can convert data from its address service into an standard address object that PayBridge understands.

Once the address is in a format understood by PayBridge, the payment adapter can pass relevant parts of the address to your payment portal.

If your forms have a custom postcode lookup, you'll need to define and register a hydrator for your address service, so PayBridge can interpret an address from it and pass the data on to your payment provider.

Defining the Hydrator

You should write a namespaced PHP class, that extends Jadu\XFormsPro\Address\AbstractAddressHydrator. The abstract class expects one method to be defined:

    /**
     * Looks up UPRN and returns Jadu Central Address object populated with return data.
     *
     * @param $uprn string
     *
     * @throws Exception
     *
     * @return Address
     */
    abstract public function getAddressFromUPRN($uprn);

This method receives the UPRN or property_identifier mapped under Include Address, and must return and complete instance of Jadu\XFormsPro\Address\Address. If it is unable to do so for any reason, it should throw an Exception, detailing what the issue was in its message.

note

Although the parameter of this function is called $uprn, the data does not necessarily have to be a true UPRN if the address service does not return one. The method should however, be able to work with the expected format of this parameter.

To be able to populate an Address object, this class must:

• Query the address service with the UPRN, to get all data for the property
• Determine how the properties of the Address object should be populated by the data returned from the address service.

note

The hydrator class is not instantiated with any arguments, so must create any classes or clients it relies on itself.

Registering the Hydrator

To register the hydrator, you need to set the hydrator against your postcode lookup component. To do this, modify the record corresponding to your postcode lookup in the JaduXFormsFormIntegratedComponents database table. Set the addressHydrator field to be the fully namespaced class name of your hydrator. The server cache must then be cleared.

note

Jadu strongly recommends making database changes via Doctrine Migrations, as manually changing the database structure can lead to accidental data loss.