Activate Business Request

Overview

Activating a Business Request always requires a mandatory location check.

• The user’s current geo-location is compared against their last active device location.

• The last active device location is:

  • The registration location if the user never changed it.

  • Or the latest login location if the user logged in from a new place.

• If the user is within 80 km, activation continues normally with OTP and payment.

• If the user is more than 80 km away, they must first revalidate liveness before proceeding.

---

Workflow

Step 1 – Confirm Location (mandatory)

• Compare current geo-location with last active device location.

---

Case A – Within 80 km

1. Request Activate OTP POST /api/BusinessRequest/CustomerSign/StepRequestOtp

2. Validate OTP POST /api/BusinessRequest/CustomerSign/StepValidateOtp

3. Validate Payment & Activate Contract :

POST /api/BusinessRequest/CustomerSign/StepValidatePayment

---

Case B – More than 80 km away

1. Request Activate OTP → system responds: “Location changed, liveness revalidation required.”

2. Revalidate Liveness POST POST /api/BusinessRequest/CustomerSign/StepRevalidteLiveness

3. Request New OTP (using the same transactionId)

4. Validate OTP

5. Validate Payment & Activate Contract

Request OTP for Business Request

post

This endpoint requests an OTP for customer sign step. The geoLocation is mandatory to verify user location.

Body

application/json

smsProvidersinteger · enumOptional

Optional. The SMS provider used to send OTP. Available options: 1- infobip, 2- vodafone, 3- Cequens, 4- victoryLink

Possible values:

requestIdstringRequired

Unique identifier of the business request

transactionIdstringOptional

Transaction identifier associated with this request

userDeviceUtcTimestring · date-timeRequired

Device UTC time of the user

paymentGatewaystringOptional

Payment gateway to be used for transaction

Responses

200

OTP request initiated successfully

application/json

post

/api/BusinessRequest/CustomerSign/StepRequestOtp

HTTPcURLJavaScriptPython

POST /api/BusinessRequest/CustomerSign/StepRequestOtp HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 174

{
  "smsProviders": 1,
  "requestId": "text",
  "transactionId": "text",
  "geoLocation": {
    "latitude": 1,
    "longitude": 1
  },
  "userDeviceUtcTime": "2026-02-12T23:33:22.973Z",
  "paymentGateway": "text"
}

200

OTP request initiated successfully

{
  "status": "text",
  "nextStep": "text"
}

Re-validate liveness step

post

This endpoint is used when a customer changes location (>80km from last active device). The user must re-validate liveness before proceeding with OTP and contract activation.

Body

application/json

requestIdstringRequired

Unique identifier of the business request

transactionIdstringRequired

Transaction identifier associated with this request (must be reused)

userDeviceUtcTimestring · date-timeRequired

Device UTC time of the user

paymentGatewaystringOptional

Payment gateway to be used for transaction

Responses

200

Liveness re-validation initiated successfully

application/json

post

/api/BusinessRequest/CustomerSign/StepReValidateLiveness

HTTPcURLJavaScriptPython

POST /api/BusinessRequest/CustomerSign/StepReValidateLiveness HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 358

{
  "scanTransaction": {
    "id_front_image": "text",
    "image": "text",
    "name_check_value": "text",
    "transaction_id": "text",
    "client_transaction_id": "text",
    "request_id": "text",
    "country": "text",
    "getExtractedData": true
  },
  "requestId": "text",
  "transactionId": "text",
  "geoLocation": {
    "latitude": 1,
    "longitude": 1
  },
  "userDeviceUtcTime": "2026-02-12T23:33:22.973Z",
  "paymentGateway": "text"
}

200

Liveness re-validation initiated successfully

{
  "status": "text",
  "nextStep": "text"
}

Validate OTP

post

https://api.example.comhttps://staging-api.example.com

/api/BusinessRequest/CustomerSign/StepValidateOtp

Validates the OTP sent to the customer during the Business Request activation process.

Authorizations

BearerAuthApiKeyAuth

AuthorizationstringRequired

JWT Bearer token authentication

Body

application/jsonapplication/json-patch+json

otpRequestIdstring · uuidRequired

Unique identifier for the OTP request.

otpCodestringRequired

The OTP code entered by the user.

requestIdstring · uuidRequired

The unique business request identifier.

transactionIdstring · uuidRequired

Transaction identifier linked to this request.

userDeviceUtcTimestring · date-timeRequired

The UTC time on the user's device.

paymentGatewaystringOptional

The payment gateway provider.

Responses

200

OTP validated successfully.

application/json

400

Invalid or expired OTP.

application/json

401

Unauthorized - Invalid authentication credentials.

application/json

422

Validation error - Invalid request data.

application/json

500

Internal server error.

application/json

post

/api/BusinessRequest/CustomerSign/StepValidateOtp

HTTPcURLJavaScriptPython

POST /api/BusinessRequest/CustomerSign/StepValidateOtp HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 292

{
  "otpRequestId": "123e4567-e89b-12d3-a456-426614174000",
  "otpCode": "text",
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "geoLocation": {
    "latitude": 1,
    "longitude": 1
  },
  "userDeviceUtcTime": "2026-02-12T23:33:22.973Z",
  "paymentGateway": "text"
}

application/jsonapplication/json-patch+json

{
  "success": true,
  "message": "text",
  "timestamp": "2026-02-12T23:33:22.973Z"
}

Validate Payment

post

https://api.example.comhttps://staging-api.example.com

/api/BusinessRequest/CustomerSign/StepValidatePayment

Validates the payment during the Business Request process.

Authorizations

BearerAuthApiKeyAuth

AuthorizationstringRequired

JWT Bearer token authentication

Body

application/jsonapplication/json-patch+json

requestIdstring · uuidRequired

The unique business request identifier.

transactionIdstring · uuidRequired

Transaction identifier linked to this request.

userDeviceUtcTimestring · date-timeRequired

The UTC time on the user's device.

paymentGatewaystringOptional

The payment gateway provider.

Responses

200

Payment validated successfully.

application/json

400

Invalid payment data.

application/json

401

Unauthorized - Invalid authentication credentials.

application/json

422

Validation error - Invalid request data.

application/json

500

Internal server error.

application/json

post

/api/BusinessRequest/CustomerSign/StepValidatePayment

HTTPcURLJavaScriptPython

POST /api/BusinessRequest/CustomerSign/StepValidatePayment HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 221

{
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "geoLocation": {
    "latitude": 1,
    "longitude": 1
  },
  "userDeviceUtcTime": "2026-02-12T23:33:22.973Z",
  "paymentGateway": "text"
}

application/jsonapplication/json-patch+json

{
  "success": true,
  "message": "text",
  "timestamp": "2026-02-12T23:33:22.973Z"
}

JavaScript

const headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json-patch+json"
};
const BASE_URL = "https://api.vlenseg.com/api";

async function makeApiCall(url, body) {
    const response = await fetch(url, {
        method: 'POST',
        headers: headers,
        body: JSON.stringify(body)
    });
    const data = await response.json();
    console.log(data);
}

// Step 1: Request OTP
makeApiCall(`${BASE_URL}/BusinessRequest/CustomerSign/StepRequestOtp`, {
    "geoLocation": {"latitude": 0, "longitude": 0},
    "userDeviceUtcTime": "2024-08-25T10:14:08.987Z"
});

// Step 2: Validate OTP
makeApiCall(`${BASE_URL}/BusinessRequest/CustomerSign/StepValidateOtp`, {
    "geoLocation": {"latitude": 0, "longitude": 0},
    "userDeviceUtcTime": "2024-08-25T10:14:25.259Z"
});

// Step 3: Perform Payment
makeApiCall(`${BASE_URL}/BusinessRequest/CustomerSign/StepProcessPayment`, {
    "paymentDetails": {"amount": 100, "currency": "USD"}
});

// Step 4: Validate Payment
makeApiCall(`${BASE_URL}/BusinessRequest/CustomerSign/StepValidatePayment`, {
    "geoLocation": {"latitude": 0, "longitude": 0},
    "userDeviceUtcTime": "2024-08-25T10:14:32.647Z"
});

Python

cURL

Web view activation workflow

Experimental

The WebView activation process consists of two main steps, which are essential for generating and viewing the contract PDF. Here’s how the process works:

Step 1: Generate Sign Contract Link

• Purpose: The first step is to generate a link for the WebView where the user can sign the contract.

• Endpoint: POST https://api.vlenseg.com/api/BusinessRequest/GenerateSignContractLink

Step 2: View Contract PDF

• Purpose: After generating the sign contract link, the next step is to view the contract PDF using the generated link.

• Endpoint: GET https://api.vlenseg.com/api/BusinessRequest/ViewContractPdf

post

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

requestIdstring · uuidOptional

contractStorageIdstring · uuid · nullableOptional

transactionIdstring · uuid · nullableOptional

userDeviceUtcTimestring · date-timeRequired

paymentGatewaystring · nullableOptional

Responses

200

Success

text/plainapplication/jsontext/json

post

/api/BusinessRequest/GenerateSignContractLink

HTTPcURLJavaScriptPython

POST /api/BusinessRequest/GenerateSignContractLink HTTP/1.1
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 280

{
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "contractStorageId": "123e4567-e89b-12d3-a456-426614174000",
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "geoLocation": {
    "latitude": 1,
    "longitude": 1
  },
  "userDeviceUtcTime": "2026-02-12T23:33:22.973Z",
  "paymentGateway": "text"
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

Success

{
  "data": "text",
  "error_code": 1,
  "error_message": "text",
  "error_descriptions": null
}

JavaScript

const headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json-patch+json"
};
const BASE_URL = "https://api.vlenseg.com/api";

async function generateSignContractLink() {
    const response = await fetch(`${BASE_URL}/BusinessRequest/GenerateSignContractLink`, {
        method: 'POST',
        headers: headers,
        body: JSON.stringify({
            "geoLocation": {"latitude": 30.193033, "longitude": 31.463339},
            "userDeviceUtcTime": "2024-08-22T12:41:28Z",
            "requestId": "81f404b3-d7dc-4f08-b4fe-934853c86282"
        })
    });
    const data = await response.json();
    console.log(data);
}

async function viewContractPdf() {
    const requestId = "c2fa8504-6b42-435b-bc01-d42078ae02a5";
    const securityHash = "a428fd4b1b49e3d32663a13bce2cdbd112ad5f2652bc3482fd5bbb7f47109207";
    const url = `${BASE_URL}/BusinessRequest/ViewContractPdf?RequestId=${requestId}&SecurityHash=${securityHash}`;

    const response = await fetch(url, {
        method: 'GET',
        headers: headers
    });
    const data = await response.json();
    console.log(data);
}

generateSignContractLink();
viewContractPdf();

Python

cURL