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.
| Domain | Environment |
|---|---|
| https://api.verifymyage.co.uk | production |
| https://api-dot-verifymyage.appspot.com | 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, for instance, has built-in methods for hash_hmac (PHP5+):
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.
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
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
}
]
}
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.
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
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
}
}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.
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
Generate HMAC with: YOUR ORDER ID
Authorization:
hmac API_ID:TIMESTAMP:GENERATED-HMAC
{
"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.
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
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"
}Copied!