Skip to main content

Single-use link

Introduction

Request

ThisBody document provides comprehensive guidance for integrating with the B-Trust identity verification service. The service enables secure identity verification through a combination of document authentication and facial recognition.

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

    La autenticación para Single-Use Link se realiza usando el estándar OAuth 2.0. Este protocolo permite gestionar de forma segura la autorización entre aplicaciones, apoyándose en tokens firmados que garantizan:

      Integridad e inalterabilidad de la información.

      Validación de origenParameters (issuer) y destinatario (audience).

      Control de tiempos de validez (expiración y emisión).

      Uso de scopes para limitar los permisos a lo estrictamente necesario.

       

      Token utilizado

      El mecanismo de autorización se basa en un token JWT (JSON Web Token) firmadoform-urlencoded):, que contiene la información mínima requerida para validar y autorizar la operación:

      Propiedad

      Parameter

      Descripción

      Description

      Tipo de token

      client_id      		 Your

      JWTclient firmadoID (JSONfor Webwebhook Token).

      authentication

      Emisor (issuer)

      client_secret      		 Your

      Indicaclient elsecret serviciofor dewebhook identidad que generó el token.

      authentication

      Destinatario (audience)

      grant_type      		 Authentication

      Especifica el sistema o servicio autorizado para recibir el tokenmethod (poruse ejemplo, el que valida Single-Use Link"client_credentials").

      Scopes / Permisos

      Determinan qué operaciones puede realizar el token. Se definen de manera granular para cumplir el principio de menor privilegio.

      Duración / Expiración

      El token tiene un ciclo de vida corto definido en el campo exp, reduciendo el riesgo de uso indebido.

      Firma

      El token está firmado con un algoritmo robusto (ej. RS256) que asegura autenticidad e integridad.

      Claims adicionales

      Incluyen información de control como:  • Identificador único de usuario (sub).  • Momento de emisión (iat).  • Restricciones de validez temporal (nbf, exp).  • Identificador único del token (jti) para mitigar reutilización.  • Otros atributos opcionales según las necesidades de autorización.

      Validación

      En el receptor se verifica: la firma, el emisor, la vigencia temporal, la audiencia y los permisos definidos en los scopes/claims.

      LoginExample Service

      Request

      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:(CURL):

      x-accountId:# AdoQaVariables de entorno
export TOKEN_URL="https://apigw-qa.ado-tech.com/api/token/TuyaQA"
export CLIENT_ID="{CLIENT_ID}"
export CLIENT_SECRET="{CLIENT_SECRET}"
export GRANT_TYPE="client_credentials"

# Petición de token
curl -X POST "$TOKEN_URL" \
  -H "Content-Type: application/jsonx-www-form-urlencoded"
      \

      Request Body:

      {--data-urlencode "username":client_id=$CLIENT_ID" \
  --data-urlencode "your-username@example.com",client_secret=$CLIENT_SECRET" \
  --data-urlencode "password": "your-password"
}
grant_type=$GRANT_TYPE"

      Example Response:

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

      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:

      Authorization: Bearer {access_token}
x-accountid: AdoQa
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://chat.openai.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://chat.openai.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:

      Authorization: Bearer {access_token}
x-accountid: AdoQa

      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://chat.openai.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 -X POST \
  '{example_host}/auth/realms/{example_realm}/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id={example_client}&client_secret={example_secret}&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.

      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:

      https://kyc-qa.ado-tech.com/AdoQa/{key}

      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">Complete Identity Verification</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:

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

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

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

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

      Example Callback Handler (Pseudocode):

      // Callback endpoint handler
app.get('/verification-callback', async (req, res) => {
  try {
    // Extract verification key from query parameters or session
    const verificationKey = req.query.key || req.session.verificationKey;
    
    // Retrieve verification status using the API
    const verificationStatus = await checkVerificationStatus(verificationKey);
    
    // Process verification result
    if (verificationStatus.success) {
      // Handle successful verification
      // Update user profile, grant access, etc.
      res.render('verification-success', { user: verificationStatus.userData });
    } else {
      // Handle failed verification
      res.render('verification-failed', { reason: verificationStatus.message });
    }
  } catch (error) {
    // Handle errors
    console.error('Verification callback error:', error);
    res.render('error', { message: 'Unable to process verification' });
  }
});

      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.

      Webhook Implementation Summary

      1. Create an endpoint in your application to receive webhook notifications.
      2. Authenticate with the webhook service to obtain a token.
      3. Process incoming verification data and update your application's user records.
      4. Respond with appropriate status codes to acknowledge receipt of the data.

      Remember that the webhook will send the complete verification result payload, including personal information, document details, and verification scores. Your webhook implementation should handle this data securely and in compliance with applicable data protection regulations.

      Back to top