Skip to main content

Stores & Custom API

Introduction#

Before starting, please check our list of plug & play integrations that can be installed in minutes at https://verifymyage.com.

API Domain#

We have two domains, one for production and one for our sandbox environment.

DomainEnvironment
https://api.verifymyage.co.ukproduction
https://api-dot-verifymyage.appspot.comsandbox

Generating the HMAC header#

To improve the security of the communication between your implementation and the VerifyMyAge API, we require you to generate a unique hexadecimal encoded SHA256 HMAC hash for each request based on the input parameters.

The process of generating it depends on the language of your implementation.

PHP, for instance, has built-in methods for hash_hmac (PHP5+):

<?php
$timestamp = time();
echo = hash_hmac('sha256', "{$API_KEY}{$timestamp}{$input}", $API_SECRET);

How does age verification work?#

Our system performs two types of verification: stealth and non-stealth.

Stealth Verification

During 'stealth' verification, we use data already gathered on your website to perform the following checks (see our privacy policy for more info).

  1. Database check: If we have verified the user previously, we confirm their age without them needing to interact with the verification process.
  2. Credit Header (and other) data: A soft lookup confirms the user is 18+ based on the credit lookup provider's data and doesn't impact their credit score.
  3. Mobile phone number: Using a user's UK mobile phone number, we can verify that they are 18+.

Non-Stealth Verification

If the 'stealth' check fails, they go through our 'non-stealth' flow.

At this point, the users can select between a list of verification methods:

  1. AI-Powered Age Estimation: A user can verify their age by taking a short selfie video.
  2. Government ID: A user can verify their age and identity using their government-issued ID such as a passport, driving licence or national ID card.
  3. Credit Card: We verify the user's credit card details to confirm they are 18+.

OAuth2 Flow

When do we need to verify?#

You need to verify your customers each time they purchase an age-restricted product.

You have two options to start an integration:

  1. Set all products to require age verification on your VerifyMyAge dashboard. Only use this option if you exclusively sell age-restricted products or when you already manage which products are age-restricted and will only call our API when you sell one of these products.
  2. Send your age-restricted products to our API before the order is placed. You'll be able to send each order to our API, and we'll handle whether or not we need to age-verify the user when a new order comes in.

OAuth2 Flow

Products#

You must indicate which products require age verification if your store sells age-restricted and non-age-restricted products.

Request parameters

products required

List of products.

id required

Unique identifier of the product on your side.

title required

The name of the product.

image required

A link to the product image on your side.

age_restricted required

true: we invoke the verification process

false: we skip the verification process

POST: /products
Generate HMAC with: FIRST PRODUCT ID
Authorization:
hmac API_ID:TIMESTAMP:GENERATED-HMAC
Request Body: (application/json)
{
  "products": [
    {
      "id": "your-first-product-id",
      "title": "First Product",
      "image": "https://mysite.com/first-product-image.jpg",
      "age_restricted": true
    },
    {
      "id": "your-second-product-id",
      "title": "Second Product",
      "image": null,
      "age_restricted": true
    }
  ]
}
Copy

Copied!

Response 204

Order#

When a new order is placed on your side, you might send it to our orders API to start the age-verification process.

Request parameters

order required

Order details with your customer data and products sold.

id required

Unique identifier of the order on your side.

customer required

Unique identifier of the order on your side.

id required

Unique identifier of the customer on your side, it can be used to search for the customer on the VMA dashboard.

first_name required

Used to compare with our data sources and to present the verification interface to the customer.

last_name required

Used to compare with our data sources and to present the verification interface to the customer.

email required

Used to send notifications to the customer.

phone optional

Despite it not being required, it is used to send notifications to the customer and is also used in stealth verification.

postcode required

Required for address fields.

address1 required

Used in stealth verification attempt.

address2 required

Despite it not being required, used in stealth verification attempts.

city required

Used in stealth verification attempts.

country required

Used in stealth verification attempts.

products required

List of products purchased.

id required

Unique identifier of the product on your side.

title required

The name of the product.

image required

A link to the product image on your side.

callback optional

Use this field if you want to receive webhook notifications when the verification status changes.

url required

URL that will receive a post request with the current status of the order.

notifications optional

Whether or not you want to send your customers notifications by email and SMS.

email required

true: an email will be sent to the user with a link to the non-stealth verification flow.

false: email will not be sent.

sms required

true: a sms will be sent to the user with a link to the non-stealth verification flow.

false: sms will not be sent.

Response parameters

id

A unique identifier generated by the VerifyMyAge API

order

Your order unique identifier

status

It represents the current status of the verification flow. It can be one of the following:

StatusDescription
ApprovedVerified 18+
PendingAwaiting customer verification
FailedCustomer failed to prove they are 18+
CancelledThe order was cancelled
IgnoredThe order doesn't contain an age-restricted product
ExpiredThe customer has not engaged with the verification flow within 5 days

url

The link you should redirect the user to so that they can complete the age verification process

POST: /orders
Generate HMAC with: YOUR ORDER ID
Authorization:
hmac API_ID:TIMESTAMP:GENERATED-HMAC
Request Body: (application/json)
{
  "order": {
    "id": "YOUR-ORDER-ID",
    "customer": {
      "id": "YOUR-ID",
      "first_name": "First Name",
      "last_name": "Last Name",
      "email": "user@email.com",
      "phone": "+44070000000",
      "postcode": "a000aa",
      "address1": "Name Street",
      "address2": "",
      "city": "London",
      "country": "UK"
    },
    "products": [
      {
        "id": "YOUR-ID",
        "image": "https://example.com/image.jpg",
        "title": "Product Name"
      }
    ]
  },
  "callback": {
    "url": "https://mysite.com/v/test"
  },
  "notifications": {
    "email": true,
    "sms": true
  }
}
Copy

Copied!

Response 200: (application/json)
{
  "id": "UNIQUE-ID",
  "order": "YOUR-UNIQUE-ID",
  "status": "Pending",
  "url": "https://verify.verifymyage.co.uk/v/VERIFYMYAGE-UNIQUE-ID"
}
Copy

Copied!

Get current order status#

Using the 'id' you can get the current status of the age-verification process for your order.

This is your order id, and will be the eBay order ID, the Shopify order ID or the Order ID you sent on the Create Orders endpoint.

Response parameters

id

A unique identifier generated by the VerifyMyAge API

order

Your order unique identifier

status

It represents the current status of the verification flow. It can be one of the following:

StatusDescription
ApprovedVerified 18+
PendingAwaiting customer verification
FailedCustomer failed to prove they are 18+
CancelledThe order was cancelled
IgnoredThe order doesn't contain an age-restricted product
ExpiredThe customer has not engaged with the verification flow within 5 days

url

The link you should redirect the user to so that they can complete the age verification process

GET: /orders/{id}
Generate HMAC with: YOUR ORDER ID
Authorization:
hmac API_ID:TIMESTAMP:GENERATED-HMAC
Response 200: (application/json)
{
  "id": "UNIQUE-ID",
  "order": "YOUR-UNIQUE-ID",
  "status": "Pending",
  "url": "https://verify.verifymyage.co.uk/v/VERIFYMYAGE-UNIQUE-ID"
}
Copy

Copied!

Webhook POST sent to your server#

Suppose you have set a callback URL to receive a POST notification when the order changes its status using the callback.url, that's how we're going to send you the updates.

We'll send you the HMAC header based on your order id, so you can compare it to ensure that we have made the API call to your server.

Request parameters

id

A unique identifier generated by the VerifyMyAge API

order

Your order unique identifier

status

It represents the current status of the verification flow. It can be one of the following:

StatusDescription
ApprovedVerified 18+
PendingAwaiting customer verification
FailedCustomer failed to prove they are 18+
CancelledThe order was cancelled
IgnoredThe order doesn't contain an age-restricted product
ExpiredThe customer has not engaged with the verification flow within 5 days

url

The link you should redirect the user to so that they can complete the age verification process

POST: https://example.com/webhook
Generate HMAC with: YOUR ORDER ID
Authorization:
hmac API_ID:TIMESTAMP:GENERATED-HMAC
Request Body: (application/json)
{
  "id": "UNIQUE-ID",
  "order": "YOUR-UNIQUE-ID",
  "status": "Pending",
  "url": "https://verify.verifymyage.co.uk/v/VERIFYMYAGE-UNIQUE-ID"
}
Copy

Copied!