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.
| Domain | Environment |
|---|---|
| https://api.verifymyage.co.uk | production |
| https://api-stg.verifymyage.co.uk | sandbox |
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
$timestamp = time();
hash_hmac('sha256', $YOUR_API_KEY . $timestamp . $input, 'API_SECRET');
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).
- Database check: If we have verified the user previously, we confirm their age without them needing to interact with the verification process.
- 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.
- 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:
- AI-Powered Age Estimation: A user can verify their age by taking a short selfie video.
- 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.
- Credit Card: We verify the user's credit card details to confirm they are 18+.
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:
- 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.
- 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.
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 idAuthorization: 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
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
}
]
}
Copied!
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 idAuthorization: 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:
| Status | Description |
|---|---|
| Approved | Verified 18+ |
| Pending | Awaiting customer verification |
| Failed | Customer failed to prove they are 18+ |
| Cancelled | The order was cancelled |
| Ignored | The order doesn't contain an age-restricted product |
| Expired | The 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 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
}
}
Copied!
{
"id": "UNIQUE-ID",
"order": "YOUR-UNIQUE-ID",
"status": "Pending",
"url": "https://verify.verifymyage.co.uk/v/VERIFYMYAGE-UNIQUE-ID"
}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 idAuthorization: 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:
| Status | Description |
|---|---|
| Approved | Verified 18+ |
| Pending | Awaiting customer verification |
| Failed | Customer failed to prove they are 18+ |
| Cancelled | The order was cancelled |
| Ignored | The order doesn't contain an age-restricted product |
| Expired | The 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} HTTP/1.1
Authorization: hmac YOUR-API-ID:TIMESTAMP:GENERATE-HMAC-WITH-YOUR-ORDER-IDCopied!
{
"id": "UNIQUE-ID",
"order": "YOUR-UNIQUE-ID",
"status": "Pending",
"url": "https://verify.verifymyage.co.uk/v/VERIFYMYAGE-UNIQUE-ID"
}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 idAuthorization: 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:
| Status | Description |
|---|---|
| Approved | Verified 18+ |
| Pending | Awaiting customer verification |
| Failed | Customer failed to prove they are 18+ |
| Cancelled | The order was cancelled |
| Ignored | The order doesn't contain an age-restricted product |
| Expired | The 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 /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"
}
Copied!