Single-use link

Single-use link

Requirements and Compatibility

Before proceeding with integration, please ensure you have the following resources and knowledge:

Access to the base URL for the identity verification service API key and project name provided by the service provider The product ID associated with the service you intend to utilize Working knowledge of HTTP GET and POST methods Authentication credentials for web services Endpoint for callback registration and webhook configuration Development environment capable of handling REST API calls Understanding of JSON request and response structures

Authentication

Login Service

To access the B-Trust API services, you must first authenticate using the login endpoint. This will provide the access token required for all subsequent requests.

Endpoint: https://api-fintecheart.ado-tech.com/api/v1/auth/login

Method: POST

Headers:

x-accountId: AdoQa
Content-Type: application/json

Request Body:

{
    "username": "your_username@domain.com",
    "password": "your_password"
}

Example Response:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIzTjZFTlpRcWVJdHdZOGtDN05VdFZsTzBUSlJaTzhsOFRkRkZQSXZzcmJzIn0...",
    "expires_in": 299,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

The access_token obtained from this response must be included in the Authorization header for all subsequent API requests, using the format Bearer {access_token}.

Identity Verification Flow Services

Create Flow Request

This endpoint allows you to create a new identity verification request, initiating the verification flow process.

Endpoint: https://api-fintecheart.ado-tech.com/api/v1/flowmanager/flowrequest/create

Method: POST

Headers:

x-accountid: AdoQa
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body Parameters:

Parameter Type Description documentType String Type of identification document (e.g., "1" for national ID) documentNumber String The identification number on the document flowType String The type of verification flow to initiate (e.g., "1" for enrollment) riskAmount Number The monetary value associated with the transaction for risk assessment callBackUrl String URL where the user will be redirected after verification

Example Request Body:

{
    "documentType": "1",
    "documentNumber": "1001818723",
    "flowType": "1",
    "riskAmount": 1230000,
    "callBackUrl": "https://your-callback-url.com/"
}

Example Response:

{
    "code": 6871,
    "typeDocument": 1,
    "document": "1001818723",
    "url": "https://kyc-qa.ado-tech.com/AdoQa/f7fb4984a8a347699e1c72cc5",
    "key": "f7fb4984a8a347699e1c72cc5",
    "flowType": "1",
    "state": 1,
    "createFor": "oscar.castañeda@ado-tech.com",
    "updateFor": "oscar.castañeda@ado-tech.com",
    "valiteKey": "2025-05-09T09:23:19.0795159Z",
    "amountRisk": 1230000,
    "customerId": 2,
    "callBackUrl": "https://your-callback-url.com/",
    "createDate": "2025-05-08T09:18:19.0795885Z",
    "project": 142,
    "customer": {
        "code": 2,
        "idAccount": "AdoQa",
        "urlAdo": "https://adocolombia-qa.ado-tech.com/ADODemo",
        "apiKey": "db92efc69991",
        "proyectNameAdo": "ADODemo",
        "urlClientFlow": "https://kyc-qa.ado-tech.com/AdoQa",
        "adoProduct": 1,
        "adoRiskId": 1,
        "styleLogo": "https://scanovate.com/wp-content/uploads/2019/07/scanovate_logo.gif",
        "styleColorPrimary": "#2851e6",
        "styleColorSecondary": "#000",
        "styleBackgroundColorBody": "#fff",
        "styleBackgroundColorContainer": "#fff",
        "styleBackgorundColorPrimaryButton": "#0076ff",
        "styleColorPrimaryTextButton": "#fff",
        "styleBackgroundColorSecondaryButton": "#eceef0",
        "styleColorSecondaryTextButton": "#8593a2"
    }
}

Response Fields:

Field Description code Internal reference code for the request typeDocument Type of identification document document The identification number url The URL to redirect the user for verification key Unique key for this verification request flowType Type of verification flow state Current state of the request (1 = created) createFor Email of user who created the request updateFor Email of user who last updated the request valiteKey Expiration datetime of the verification key amountRisk Monetary value for risk assessment customerId Customer ID in the system callBackUrl URL where user will be redirected after verification createDate Creation datetime of the request project Project ID in the system customer Object containing customer configuration details

Retrieve Flow Request

This endpoint allows you to retrieve information about an existing verification request.

Endpoint: https://api-fintecheart.ado-tech.com/api/v1/flowmanager/flowrequest/byId

Method: GET

Headers:

x-accountid: AdoQa
Authorization: Bearer {access_token}

Query Parameters:

Parameter Description key The unique key of the verification request

Example Request:

GET https://api-fintecheart.ado-tech.com/api/v1/flowmanager/flowrequest/byId?key=b74bfc9040924f06a419dacc2

Example Response:

{
    "success": true,
    "message": "get successfull",
    "flowRequestData": {
        "documentType": 1,
        "documentNumber": "1234097206",
        "flowUrl": "https://kyc-qa.ado-tech.com/AdoQa",
        "flowKey": "b74bfc9040924f06a419dacc2",
        "flowType": "1",
        "state": "created",
        "createdBy": "oscar.castañeda@ado-tech.com",
        "updateBy": "oscar.castañeda@ado-tech.com",
        "createDate": "2025-02-18T10:05:45.131812Z",
        "riskAmount": 1230000,
        "customerId": 2,
        "callbackUrl": "https://your-callback-url.com/"
    }
}

Response Fields:

Field Description success Boolean indicating if the request was successful message Message describing the result of the operation flowRequestData Object containing the verification request data documentType Type of identification document documentNumber The identification number on the document flowUrl Base URL for the verification flow flowKey Unique key for this verification request flowType Type of verification flow state Current state of the request createdBy Email of user who created the request updateBy Email of user who last updated the request createDate Creation datetime of the request riskAmount Monetary value for risk assessment customerId Customer ID in the system callbackUrl URL where user will be redirected after verification

Webhook Integration

Webhooks allow your system to receive real-time notifications when a verification process is completed. This section details how to set up and handle webhook callbacks.

Webhook Authentication

Before receiving webhook notifications, you must authenticate to obtain a token.

Endpoint: {example_host}/auth/realms/{example_realm}/protocol/openid-connect/token

Method: POST

Headers:

Content-Type: application/x-www-form-urlencoded

Request Body Parameters (form-urlencoded):

Parameter Description client_id Your client ID for webhook authentication client_secret Your client secret for webhook authentication grant_type Authentication method (use "client_credentials")

Example Request (CURL):

curl --location --globoff '{example_host}/auth/realms/{example_realm}/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={example_client}' \
--data-urlencode 'client_secret={example_secret}' \
--data-urlencode 'grant_type=client_credentials'

Example Response:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIzTjZFTlpRcWVJdHdZOGtDN05VdFZsTzBUSlJaTzhsOFRkRkZQSXZzcmJzIn0...",
    "expires_in": 299,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

Receiving Verification Process Data

Your webhook endpoint should be prepared to receive notifications when a verification process is completed.

Webhook Endpoint: {example_host}/{example_data_call_back}

Method: POST

Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Example Webhook Payload:

{
    "Uid": "b2b731bc-785c-410e-80a4-27cb82215956",
    "key": "c511dd3154264283aa226fbe9",
    "StartingDate": "2023-09-07T10:55:26.603",
    "CreationDate": "2023-09-07T10:55:47.99",
    "CreationIP": "186.82.84.1",
    "DocumentType": 1,
    "IdNumber": "1001818723",
    "FirstName": "CARLOS",
    "SecondName": "HABID",
    "FirstSurname": "VERGEL",
    "SecondSurname": "BARRAZA",
    "Gender": "M",
    "BirthDate": "2002-08-30T00:00:00",
    "PlaceBirth": "BARRANQUILLA (ATLANTICO)",
    "ExpeditionCity": null,
    "ExpeditionDepartment": null,
    "BirthCity": null,
    "BirthDepartment": null,
    "TransactionType": 1,
    "TransactionTypeName": "Enroll",
    "IssueDate": "2020-09-03T00:00:00",
    "TransactionId": "125",
    "ProductId": "1",
    "ComparationFacesSuccesful": false,
    "FaceFound": false,
    "FaceDocumentFrontFound": false,
    "BarcodeFound": false,
    "ResultComparationFaces": 0.0,
    "ComparationFacesAproved": false,
    "Extras": {
        "IdState": "4",
        "StateName": "Documento auténtico, sin cotejo facial"
    },
    "NumberPhone": null,
    "CodFingerprint": null,
    "ResultQRCode": null,
    "DactilarCode": null,
    "ReponseControlList": null,
    "Images": [],
    "SignedDocuments": [],
    "Scores": [
        {
            "Id": 4,
            "UserName": null,
            "StateName": "Documento auténtico, sin cotejo facial",
            "StartingDate": "0001-01-01T00:00:00",
            "Observation": null
        }
    ],
    "Response_ANI": null,
    "Parameters": null
}

Webhook Response:

Your webhook endpoint should respond with a 200 OK status to acknowledge receipt of the data. You may include additional information in your response as needed.

{
    "status": "received",
    "message": "Verification data processed successfully"
}

Webhook Payload Fields:

Field Description Uid Unique identifier for this verification process key Key that matches the flow request key StartingDate Date and time when the verification process started CreationDate Date and time when the verification record was created CreationIP IP address from which the verification was initiated DocumentType Type of identification document IdNumber Identification number from the document FirstName First name of the verified individual SecondName Second name of the verified individual FirstSurname First surname/last name of the verified individual SecondSurname Second surname/last name of the verified individual Gender Gender of the verified individual BirthDate Date of birth of the verified individual PlaceBirth Place of birth of the verified individual TransactionType Type of transaction (1 = Enroll) TransactionTypeName Name of the transaction type IssueDate Date when the identification document was issued TransactionId Unique identifier for the transaction ProductId Identifier of the product used for verification ComparationFacesSuccesful Boolean indicating if facial comparison was successful FaceFound Boolean indicating if a face was detected FaceDocumentFrontFound Boolean indicating if a face was found on the front of the document BarcodeFound Boolean indicating if a barcode was detected and read ResultComparationFaces Numerical score of facial comparison ComparationFacesAproved Boolean indicating if the facial comparison met approval threshold Extras Object containing additional verification data Scores Array of assessment scores for the verification

User Redirection

After creating a verification request, you should redirect the user to the URL provided in the response:

url: "https://kyc-qa.ado-tech.com/AdoQa/f7fb4984a8a347699e1c72cc5"

This URL contains the unique key for the verification request and enables the user to complete the identity verification process through a secure web interface.

Redirection Methods

You can implement user redirection using various approaches:

HTML Link:

<a href="https://kyc-qa.ado-tech.com/AdoQa/f7fb4984a8a347699e1c72cc5" target="_blank">Start Verification Process</a>

JavaScript Redirection:

window.location.href = "https://kyc-qa.ado-tech.com/AdoQa/f7fb4984a8a347699e1c72cc5";

Server-Side Redirection (Example in Node.js):

res.redirect("https://kyc-qa.ado-tech.com/AdoQa/f7fb4984a8a347699e1c72cc5");

Handling the Callback

The callBackUrl parameter specified when creating a flow request is crucial as it defines where the user will be redirected after completing the verification process. Your application should be prepared to handle this callback:

Capture URL Parameters: Set up your callback endpoint to capture query parameters that may contain status information.

Verification Status Check: After receiving a callback, use the "Retrieve Flow Request" endpoint to get the current status and details of the verification process.

User Experience: Display appropriate feedback to the user based on the verification result (success, pending, failure).

Process Results: Update your application's user records and proceed with the appropriate business logic based on the verification outcome.

Example Callback Handler (Pseudocode):

app.get('/verification-callback', async (req, res) => {
  // Extract key from query parameters
  const key = req.query.key;
  
  // Call the API to get verification status
  const verificationStatus = await getVerificationStatus(key);
  
  // Process the status and respond to the user
  if (verificationStatus.flowRequestData.state === 'completed') {
    // Success logic
    res.render('verification-success');
  } else if (verificationStatus.flowRequestData.state === 'failed') {
    // Failure logic
    res.render('verification-failed');
  } else {
    // Pending or other states
    res.render('verification-pending');
  }
});

Advanced Integration Considerations

Security Best Practices

Token Management:

Store authentication tokens securely Implement token refresh mechanisms Never expose tokens in client-side code

Data Encryption:

Use HTTPS for all API communications Consider encrypting sensitive data before transmission Implement secure storage for verification results

Error Handling:

Implement robust error handling for API failures Provide friendly user feedback for verification issues Log errors for troubleshooting and security monitoring

Performance Optimization

Caching Strategy:

Cache verification status when appropriate Implement efficient state management to reduce API calls

Connection Pooling:

Reuse HTTP connections when making multiple API calls Configure appropriate timeout settings

Customization Options

The B-Trust system allows extensive customization of the verification experience:

Branding: The customer object in the response contains various styling parameters that define the look and feel of the verification interface:

styleLogo: URL to your company logo styleColorPrimary: Primary color for UI elements styleColorSecondary: Secondary color for UI elements styleBackgroundColorBody: Background color for the page body styleBackgroundColorContainer: Background color for containers styleBackgorundColorPrimaryButton: Background color for primary buttons styleColorPrimaryTextButton: Text color for primary buttons styleBackgroundColorSecondaryButton: Background color for secondary buttons styleColorSecondaryTextButton: Text color for secondary buttons

Risk Assessment: The riskAmount parameter allows adjustment of the verification process according to the transaction value and associated risk level.

Flow Types: Different flowType values enable various verification workflows tailored to specific use cases:

Type "1": Standard enrollment process Other types: Contact your service provider for additional flow options

Error Handling and Troubleshooting

Common Error Scenarios

Authentication Failures:

Ensure credentials are correct Check token expiration Verify account permissions

Invalid Parameters:

Validate all input parameters before sending Check document type compatibility Ensure document numbers match expected formats

Callback Issues:

Confirm callback URL is publicly accessible Ensure URL encoding is handled properly Check for firewall or security restrictions

Debugging Tips

Logging: Implement comprehensive logging for all API interactions to facilitate troubleshooting.

Testing Environment: Utilize the QA environment (https://kyc-qa.ado-tech.com) for testing before moving to production.

Postman Collections: Use the provided Postman collection for manual testing and exploration of the API