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

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

Single-use link

Single-use link

Requirements and Compatibility

Authentication

Login Service

Identity Verification Flow Services

Create Flow Request

Retrieve Flow Request

Webhook Integration

Webhook Authentication

Receiving Verification Process Data

User Redirection

Redirection Methods

Handling the Callback

Example Callback Handler (Pseudocode):

Advanced Integration Considerations

Security Best Practices

Performance Optimization

Customization Options

Error Handling and Troubleshooting

Common Error Scenarios

Debugging Tips