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.

Postman Workspace

We've created a Postman workspace specifically for our API, which contains example API calls that you can use to test and familiarise yourself with our API.

The workspace includes example API calls for each of our API endpoints, along with detailed descriptions of the request parameters and headers being used.

You can generate most of the client code to call our APIs using the Postman client code generator. With this feature, developers can select a range of programming languages, and generate the corresponding code with a few clicks.

Please note that while both the example API calls and the generated code can be a helpful starting point, it's important to thoroughly test your own API calls before deploying them in production. If you encounter any issues while using the example API calls, or if you have any questions about our API, please don't hesitate to reach out to our support team.

API Domain

Our API is designed to be used in two environments: a sandbox environment and a production environment.

The sandbox environment is intended for testing and development purposes, while the production environment is used for live data and real-world use cases.

To ensure the security and integrity of our API, we use separate API keys for each environment. This means that you will need to obtain different API keys for the sandbox and production environments, and should not use the same key for both.

DomainEnvironment
https://api.verifymyage.co.ukproduction
https://api-stg.verifymyage.co.uksandbox

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.

Example
phpnode.js
<?php
    
$timestamp = time();
hash_hmac('sha256', $YOUR_API_KEY . $timestamp . $input, 'API_SECRET');
Copy

Copied!

import { HmacSHA256 } from 'crypto-js';

const time = (new Date).getTime();
HmacSHA256(`${YOUR_API_KEY}${time}${input}`, 'API_SECRET').toString()
Copy

Copied!

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.

Authorization Header

Generate HMAC with: First product id
Authorization: hmac API_ID:TIMESTAMP:GENERATED-HMAC

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

Error responses

CodeDescription
422
{"errors": ["products" is required"]}
Copy

Copied!

422
{"errors": ["Invalid timestamp"]}
Copy

Copied!

422
{"errors": ["Product "id" and "title" must be sent"]}
Copy

Copied!

422
{"errors": ["HMAC is not valid"]}
Copy

Copied!

500
Internal Server Error
Copy

Copied!

API Call
httpcurl
POST /products HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-FIRST-PRODUCT-ID

{
    "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!

curl -d '{"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}]}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-FIRST-PRODUCT-ID" \
-X POST https://api.verifymyage.co.uk/products
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.

Authorization Header

Generate HMAC with: Your order id
Authorization: hmac API_ID:TIMESTAMP:GENERATED-HMAC

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

Error responses

CodeDescription
422
{"errors": ["Invalid authorization header format"]}
Copy

Copied!

422
{"errors": ["Customer is required"]}
Copy

Copied!

422
{"errors": ["Customer < id | first_name | last_name | address1 | city | country > is required"]}
Copy

Copied!

422
{"errors": ["Order id is required"]}
Copy

Copied!

422
{"errors": ["At least one item in "products" is required"]}
Copy

Copied!

422
{"errors": ["Order "products" id and title must be sent"]}
Copy

Copied!

422
{"errors": ["HMAC is not valid"]}
Copy

Copied!

500
Internal Server Error
Copy

Copied!

502
<HTML>
Copy

Copied!

API Call
httpcurl
POST /orders HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-YOUR-ORDER-ID

{
    "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!

curl -d '{"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}}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-YOUR-ORDER-ID" \
-X POST https://api.verifymyage.co.uk/orders
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.

Authorization Header

Generate HMAC with: Your order id
Authorization: hmac API_ID:TIMESTAMP:GENERATED-HMAC

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

Error responses

CodeDescription
422
{"errors": ["Invalid authorization header format"]}
Copy

Copied!

422
{"errors": ["HMAC is not valid"]}
Copy

Copied!

404
{"errors": ["Could not find order"]}
Copy

Copied!

500
Internal Server Error
Copy

Copied!

API Call
httpcurl
GET /orders/{id} HTTP/1.1
Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-YOUR-ORDER-ID
Copy

Copied!

curl -H "Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-YOUR-ORDER-ID" https://api.verifymyage.co.uk/orders/{id}
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!

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.

Authorization Header

Generate HMAC with: Your order id
Authorization: hmac API_ID:TIMESTAMP:GENERATED-HMAC

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

Webhook Call
httpcurl
POST /your-path HTTP/1.1
Host: https://your-domain.com
Content-Type: application/json
Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-YOUR-ORDER-ID

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

Copied!

curl -d '{"id": "UNIQUE-ID", "order": "YOUR-UNIQUE-ID", "status": "Pending", "url": "https://verify.verifymyage.co.uk/v/VERIFYMYAGE-UNIQUE-ID"}' \
-H "Content-Type: application/json" \
-H "Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-YOUR-ORDER-ID" \
-X POST https://your-domain.com/your-path
Copy

Copied!