Amani Web SDK Integration Guide

The Amani Web SDK allows you to seamlessly integrate Know Your Customer (KYC) processes, Videocall processes and Biometric Payment (Bio Pay) verification into your web applications.

Integration Workflow

1. Authentication – Obtain an access token via server-side request.
2. Create Profile – Register or retrieve a customer profile.
3. Generate SDK URL – Create a unique verification session.
4. User Redirection – Direct the user to the Amani Web Interface.
5. Callback Handling – Handle the user's return to your application.

---

Step 1: Authentication

To interact with the Amani API, you must first authenticate. This request must be performed server-side to keep your credentials secure.

Endpoint: POST https://{region}.amani.ai/api/v2/user/login/

# Replace {region} with your assigned region (e.g., 'eu1', 'tr1')
curl --location --request POST 'https://{region}.amani.ai/api/v2/user/login/' \
--form 'username="your_email@account.com"' \
--form 'password="your_password"'

IMPORTANT Use the access token from the response for all subsequent API calls using the Authorization: Bearer {token} header.

---

Step 2: Create or Get Profile

Create a profile for your customer. If a customer already exists with the provided id_card_number, the existing profile details will be returned.

Endpoint: POST https://{region}.amani.ai/api/v2/profile

curl --location --request POST 'https://{region}.amani.ai/api/v2/profile' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'id_card_number="CUSTOMER_ID_NUMBER"' \
--form 'name="Customer Name"' \
--form 'email="customer@email.com"' \
--form 'phone="+905..." '

Note: Save the id (Profile ID) from the response for the next step.

---

Step 3: Generate Verification URL

Generate a secure, short-lived URL for your customer to complete the verification process.

Request:

curl --location --request POST 'https://{region}.amani.ai/api/v2/profile/url' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{
    "profile": PROFILE_ID,
    "web_sdk_url": "https://verify.amani.ai",
    "geo_location": false,
    "language": "en",
    "return_url": "https://yourdomain.com/verification-complete",
    "deep_link": ""
  }'

Parameters:

Parameter	Type	Required	Description
profile	string	✅ Yes	Profile ID from the previous step
web_sdk_url	string	✅ Yes	Base URL for Amani's Web SDK (typically https://verify.amani.ai)
geo_location	boolean	⚪ Optional	Enable geolocation tracking (default: false)
language	string	⚪ Optional	Language code (default: en) - See supported languages
return_url	string	✅ Yes	URL to redirect user after verification completes
deep_link	string	⚪ Optional	Custom deep link for mobile integration

Videocall Integration

IMPORTANT To enable Videocall functionality, simply append /call to your web_sdk_url.

Example: If your base URL is https://verify.amani.ai, use https://verify.amani.ai/call for Videocall processes.

Response:

{
  "short_url": "https://verify.amani.ai?pid=be1a2e01HX79R....A757XPS&server_url=https://{region}.amani.ai"
}

Note: Store the short_url for the next step.

---

Step 4: Redirecting the User

Direct your users to complete verification by using the short_url provided in the previous step. You can redirect via iframe or browser window.

Implementation Methods

Option 1: Direct Redirect

Redirect users directly to the Amani Web SDK interface:

window.location.href = { short_url };

Option 2: iFrame Integration

Embed the verification process within your application:

<iframe src="{short_url}" width="100%" height="600" frameborder="0"> </iframe>

---

Step 5: Handling the Callback

After the user completes verification or encounters an error, they are automatically redirected to your return_url with the following query parameters:

• status: The customer's verification status (e.g., complete, incomplete).
• customer_id: The Amani Profile ID.
• errors: A comma-separated list of error codes if the process failed.

Error Code Reference

Code	Meaning
401	Unauthorized: Token is invalid or expired.
404	Not Found: User profile could not be located.
500	Internal Server Error.

---

Bio Pay Integration

Bio Pay is a specialized module for biometric payment authentication using facial recognition and PIN verification.

Implementation

Direct users to the Bio Pay interface using a pre-generated bio_token:

https://verify.amani.ai?bio_token={YOUR_BIO_TOKEN}&server_url={YOUR_SERVER_URL}

Parameters:

Parameter	Description
bio_token	Pre-generated authentication token for the user
server_url	Your regional API server URL (e.g., https://{region}.amani.ai)

Prerequisites:

• A valid user with necessary permissions.
• Biopay feature enabled on your account.