Introduction

This verification method compares an address registered to a bank card to that registered against a smart meter that an end user is attempting to grant consent for. Address verification, or AVS checks, are commonly used to verify that a payment card is registered at a particular address.

Definitions

Term	Description
MobileApp	The third party app
ServerApp	The third party backend serving information to the MobileApp
End User	The person user the MobileApp
Glow User	The user entity in the Glow Platform that represent the End User
Stripe Customer	The customer record in Stripe that represents the End User
Stripe	The chosen external payment provider
Glow userId	The UUID of the Glow User

Implementation

The below implementation guide uses Stripe as an external payment provider. In Stripe, we do not want to run a payment authorisation for the person that is being verified, so one of the routes to invoke AVS is the tokenisation of a payment card.

The tokenisation information can include a first line of address and postcode, along with the card number, expiration date and CV2 numbers. The idea is to match 3 addresses; the billing address the end user provides, the billing address registered against the card details and the address stored in the DCC Inventory. During the AVS check Stripe will advice whether the billing address provided is associated to the credit card (see event payloads below). If that passes, we proceed to comparing the address to the one in the DCC Inventory.

Requirements

The end user needs to input their MPxN and bank card information (including the address information). Stripe webhooks will need to be configured to send events to the GlowAPI as well as any support needed by the ServerApp or MobileApp.

In the sections below we will first explore the 4 main process flows that can be used to implement Smart Meter Onboarding via AVS. This will be followed by the respective API definitions, and finally we will conclude with examples on Stripe structures.

Process Description

There are 4 different process flows available for onboarding a smart meter with the AVS Address Verification method. These flows differ with regards to 2 parameters; firstly whether the Glow userId is known at the time the Stripe Customer gets created, and secondly whether the Glow User is being created simultaneously with the smart meter onboard.

In the table below each process flow is outlined along with the Stripe webhooks and the Glow APIs that will need to be used in each case. To demonstrate the differences between the process flows we define:

Preexisting Stripe Customer - The Stripe Customer was created without setting the Glow userId to the description. This would mean that the Server App would need to update the customer record on Stripe prior to proceeding with the smart meter registration. In these scenarios, the Stripe Update Customer API can be used and the webhook that needs to be set up is the customer.updated .

Preexisting Glow User - The Glow User was created prior to the smart meter onboard.

Please note that for the third party integration you can switch between using the Glow API 1 and 2. However it is highly advisable that only one Stripe webhook related to the customer is used (either customer.created or customer.updated ).

Case	Process Flow Description	Preexisting Stripe Customer	Preexisting Glow User	Stripe Webhooks to configure	Glow API to use
1	Stripe Customer and Glow User are registered at the same time the meter is onboarded. (API 1)	false	false	- customer.created - payment_method.attached	API 1
2	Glow User and Stripe Customer (Stripe Customer is tied to Glow User at creation) preexist at the time the smart meter is onboarded. (API 2)	false	true	- customer.created - payment_method.attached	API 2
3	Stripe Customer preexists and was created without assigning a Glow userId to description. Glow User is registered at the same time the meter is onboarded. (API 1)	true	false	- customer.updated - payment_method.attached	API 1
4	Stripe Customer preexists and was created without assigning a Glow userId to description. Glow User also preexists at the time the smart meter is onboarded. (API 2)	true	true	- customer.updated - payment_method.attached	API 2

Process Flow 1

Stripe Customer and Glow User is registered at the same time the meter is onboarded. (API 1)

Process Flow 2

Glow User and Stripe Customer (Stripe Customer is tied to Glow User at creation) preexist at the time the smart meter is onboarded. (API 2)

Process Flow 3

Stripe Customer preexists and was created without assigning a Glow userId to description. Glow User is registered at the same time the meter is onboarded. (API 1)

Process Flow 4

Stripe Customer preexists and was created without assigning a Glow userId to description. Glow User also preexists at the time the smart meter is onboarded. (API 2)

APIs for Smart Meter Onboarding via AVS Address Verification

Register user and onboard smart meter and verify via AVS Address Verification

Onboard smart meter and verify via AVS Address Verification for existing userId

Responses

Synchronous response

All responses will contain a prenotification ID. This can be used to query the status of a given smart meter onboard. Further information to be provided.

Asynchronous response

The Glow API will be notified by the payment provider asynchronously. It will onboard the smart meter if the AVS succeeds and matches the DCC address, or report an error if it fails. Notifying the Server App on the success/failure of these events will happen via Webhooks. The below 2 events will be generated. For information on how to setup webhooks, please refer to the document entitled GlowPlatformDccCallbackNotes_v13.md .

These events are generated as an asynchronous response to the APIs used for Smart meter onboarding via AVS Address Verification.

On Success

Event	Payload	Description	JSON payload
smart-meter-avs-onboard.success	- MPXN - userId -applicationId	These events are generated as a successful asynchronous response to the AVS. This means that the system will register the smart meters against the user.	{ "applicationId": "b0f1b774-a586-4f72-9edd-27ead8aa7a8d", "eventType": "smart-meter-avs-onboard.success", "data": { "userId": "0f580541-7139-43d3-826f-a63655b73c89", "mpxn": "1111111122228" } }

On Failure

Event	Payload	Description	JSON payload
smart-meter-avs-onboard.failure	-- MPXN - userId - applicationId	These events are generated as an unsuccessful asynchronous response to the AVS. This means that the system will register the smart meters against the user. The error codes with details are provided in the SmarterMeterOnboardingViaAVS(Stripe) documentation.	{ "applicationId": "b0f1b774-a586-4f72-9edd-27ead8aa7a8d", "eventType": "smart-meter-avs-onboard.success", "data": { "userId": "0f580541-7139-43d3-826f-a63655b73c89", "mpxn": "1111111122228", "errorCode":"ERROR_CODE" "errorDetails": {} } }

The AVS Failure ErrorCodes are the following:

ErrorCode	Description
AVS_BAD_PAYMENT_METHOD	Payment method not attached to cusotmer, it was rejected for some reason by stripe
MPXN_NO_DCC_ADDRESS	MPXN has no address in the DCC.
AVS_FAILS	AVS fails (billing address provided does not match card billing address)
AVS_MPXN_ADDRESS_MISMATCH	DCC address does not match incoming billing address

Setting up webhooks in Stripe

https://docs.stripe.com/webhooks#register-webhook

The event types of interest are the following:

customer.created OR customer.updated

payment_method.attached

The endpoint to set up the webhooks to is:

Examples of Webhook responses from Stripe

Event: customer.created

{
  "object": {
    "id": "cus_NsJ5YtQ7qPzfUX",
    "object": "customer",
    "address": null,
    "balance": 0,
    "created": 1683807587,
    "currency": null,
    "default_source": null,
    "delinquent": false,
    "description": "2f828329-55cd-456b-9123-05d07fa9e1cc",
    "discount": null,
    "email": null,
    "invoice_prefix": "55CA31B0",
    "invoice_settings": {
      "custom_fields": null,
      "default_payment_method": null,
      "footer": null,
      "rendering_options": null
    },
    "livemode": false,
    "metadata": {
    },
    "name": null,
    "phone": null,
    "preferred_locales": [
    ],
    "shipping": null,
    "tax_exempt": "none",
    "test_clock": null
  }
}

Event: customer.updated

{
  "object": {
    "id": "cus_NsJ5YtQ7qPzfUX",
    "object": "customer",
    "address": null,
    "balance": 0,
    "created": 1683807587,
    "currency": null,
    "default_source": null,
    "delinquent": false,
    "description": "2f828329-55cd-456b-9123-05d07fa9e1cc",
    "discount": null,
    "email": null,
    "invoice_prefix": "55CA31B0",
    "invoice_settings": {
      "custom_fields": null,
      "default_payment_method": null,
      "footer": null,
      "rendering_options": null
    },
    "livemode": false,
    "metadata": {
    },
    "name": null,
    "phone": null,
    "preferred_locales": [
    ],
    "shipping": null,
    "tax_exempt": "none",
    "test_clock": null
  }
}

Event: payment_method.attached

Successful card postcode check

All 3 should pass

{
          "address_line1_check": "pass",
          "address_postal_code_check": "pass",
          "cvc_check": "pass"
        },

{
  "id": "evt_1N6Xd9DOZzcVYvZSFp1IUJp8",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1683804354,
  "data": {
    "object": {
      "id": "pm_************************",
      "object": "payment_method",
      "billing_details": {
        "address": {
          "city": "London",
          "country": null,
          "line1": "Street Name",
          "line2": "123A",
          "postal_code": "A00 A00",
          "state": null
        },
        "email": null,
        "name": "Justin Testing",
        "phone": null
      },
      "card": {
        "brand": "visa",
        "checks": {
          "address_line1_check": "pass",
          "address_postal_code_check": "pass",
          "cvc_check": "pass"
        },
        "country": "US",
        "exp_month": 7,
        "exp_year": 2026,
        "fingerprint": "************",
        "funding": "credit",
        "generated_from": null,
        "last4": "4242",
        "networks": {
          "available": [
            "visa"
          ],
          "preferred": null
        },
        "three_d_secure_usage": {
          "supported": true
        },
        "wallet": null
      },
      "created": 1683804354,
      "customer": "cus_NsHWPrRrruAkIu",
      "livemode": false,
      "metadata": {},
      "type": "card"
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": "req_eTST0K7NYyHA4K",
    "idempotency_key": "6014083d-da1e-4c22-86f5-804dff000156"
  },
  "type": "payment_method.attached"
}

Failed card check

Here the billing address provided by the user does not match the billing address of the card, resulting to the Stripe event indicating that "address_postal_code_check" is false.

{
  "id": "evt_1N6XhmDOZzcVYvZSlRxgTdED",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1683804642,
  "data": {
    "object": {
      "id": "pm_************************",",
      "object": "payment_method",
      "billing_details": {
        "address": {
          "city": "London",
          "country": null,
          "line1": "Street Name",
          "line2": "123A",
          "postal_code": "A00 A00",
          "state": null
        },
        "email": null,
        "name": "Justin Testing",
        "phone": null
      },
      "card": {
        "brand": "visa",
        "checks": {
          "address_line1_check": "pass",
          "address_postal_code_check": "fail",
          "cvc_check": "pass"
        },
        "country": "US",
        "exp_month": 2,
        "exp_year": 2044,
        "fingerprint": "************",
        "funding": "credit",
        "generated_from": null,
        "last4": "0036",
        "networks": {
          "available": [
            "visa"
          ],
          "preferred": null
        },
        "three_d_secure_usage": {
          "supported": true
        },
        "wallet": null
      },
      "created": 1683804641,
      "customer": "cus_NsHWPrRrruAkIu",
      "livemode": false,
      "metadata": {},
      "type": "card"
    }
  },
  "livemode": false,
  "pending_webhooks": 3,
  "request": {
    "id": "req_35g2UeX1asmS90",
    "idempotency_key": "4be614bc-ac44-4117-83cb-c2de310c2ff0"
  },
  "type": "payment_method.attached"
}

Testing with Stripe

Please set up tests with the following cards:

https://stripe.com/docs/testing?locale=en-GB#fraud-prevention

- Postal code check fails

- Line1 check fails

- Address checks fail

- Address unavailable

Our current understanding is that if you pass in a test address it should come through to the events. So as a billing address try to pass the DCC address with a card that would go though.

If this does not work you could explore this:

https://stripe.com/docs/testing?locale=en-GB#webhooks

Other Material

What the customer looks like in Stripe

Customer object needs to be created for each user, the userId can be attached as the description.

{
    "id": "cus_NsJ5YtQ7qPzfUX",
    "object": "customer",
    "address": null,
    "balance": 0,
    "created": 1683807587,
    "currency": null,
    "default_source": null,
    "delinquent": false,
    "description": "2f828329-55cd-456b-9123-05d07fa9e1cc",
    "discount": null,
    "email": null,
    "invoice_prefix": "55CA31B0",
    "invoice_settings": {
        "custom_fields": null,
        "default_payment_method": null,
        "footer": null,
        "rendering_options": null
    },
    "livemode": false,
    "metadata": {},
    "name": null,
    "phone": null,
    "preferred_locales": [],
    "shipping": null,
    "tax_exempt": "none",
    "test_clock": null
}

AVS Check

Introduction#

Definitions#

Implementation#

Requirements#

Process Description#

Process Flow 1#

Process Flow 2#

Process Flow 3#

Process Flow 4#

APIs for Smart Meter Onboarding via AVS Address Verification#

Register user and onboard smart meter and verify via AVS Address Verification#

Onboard smart meter and verify via AVS Address Verification for existing userId#

Responses#

Synchronous response#

Asynchronous response#

On Success#

On Failure#

Setting up webhooks in Stripe#

Examples of Webhook responses from Stripe#

Event: customer.created#

Event: customer.updated#

Event: payment_method.attached#

Successful card postcode check#

Failed card check#

Testing with Stripe#

Other Material#

What the customer looks like in Stripe#