Equifax Integration

Integration with Equifax credit bureau for credit reports and scoring in Ecuador

Overview

The Equifax integration provides comprehensive credit bureau services, enabling retrieval of credit reports, credit scores, debt analysis, and financial risk assessment for individuals and businesses in Ecuador.

Architecture

The integration consists of three main components:

1. EquifaxService - HTTP client for API communication (Services/ApiEquifax/EquifaxService.cs)
2. OAuthEquifaxTokenService - OAuth 2.0 token management
3. ApiEquifaxRepository - Data persistence layer (Services/ApiEquifax/ApiEquifaxRepository.cs)

Authentication

Equifax uses OAuth 2.0 Bearer token authentication:

• Token is automatically managed by OAuthEquifaxTokenService
• Tokens are refreshed as needed
• All API requests include the Bearer token in the Authorization header

Service Methods

ObtenerReportePorIdentificacion

Retrieves a comprehensive credit report for an individual or business by their identification number.

Location: Services/ApiEquifax/EquifaxService.cs:23-60

Parameters

identificacion · String! · required

Identification number (Cédula or RUC)

tipoDocumento · TipoDocumento · default: "Cedula"

Document type. Options:

• Cedula - National ID card
• RUC - Tax identification number
• Pasaporte - Passport

Response Structure

The method returns a ReporteCrediticio object containing:

resumenInforme · List<ResumenInforme>

Summary of the credit report

scoreInclusion · List<ScoreInclusion>

Financial inclusion score data

score · List<ScoreEquifax>

Primary credit score information

scoreSobreendeudamiento · List<ScoreSobreendeudamiento>

Over-indebtedness score analysis

indicadorImpactoEconomico · List<IndicadorImpactoEconomico>

Economic impact indicators

historicoScore · List<HistoricoScore>

Historical credit score evolution

historicoAcreedores · List<HistoricoAcreedores>

Historical creditor information

historicoCuotaEstimada · List<HistoricoCuotaEstimada>

Historical estimated payment information

historicoEndeudamientoComercial · List<HistoricoEndeudamientoComercial>

Historical commercial debt data

historicoEndeudamientoFinanciero · List<HistoricoEndeudamientoFinanciero>

Historical financial debt data

historicoVencidosComercial · List<HistoricoVencidosComercial>

Historical overdue commercial obligations

historicoVencidosFinanciero · List<HistoricoVencidosFinanciero>

Historical overdue financial obligations

valorDeuda3Sistemas · List<ValorDeuda3Sistemas>

Debt values across three financial systems

protestosMorosidades · List<ProtestosMorosidades>

Protests and payment defaults

evolucionDeudaSbSepsSicom · List<EvolucionDeudaSbSepsSicom>

Debt evolution in banking, cooperatives, and commercial sectors

detalleDeudaHistoricaSicom · List<DetalleDeudaHistoricaSicom>

Historical commercial debt details

detalleDeudaHistoricaSeps · List<DetalleDeudaHistoricaSeps>

Historical cooperative debt details

detalleDeudaHistoricaSb · List<DetalleDeudaHistoricaSb>

Historical banking debt details

factoresInfluyenScore · List<FactoresInfluyenScore>

Factors influencing the credit score

entidadesConsultados · List<EntidadesConsultados>

Entities that have queried this credit report

Repository Operations

The ApiEquifaxRepository provides database operations for caching and retrieving Equifax data.

Create

Stores a new Equifax report in the database.

Task<ApiEquifaxDTO> Create(ApiEquifaxDTO apiEquifax)

GetById

Retrieves an Equifax report by its ID.

Task<ApiEquifaxDTO> GetById(int id)

GetById30Valid

Retrieves an Equifax report only if it was created within the last 30 days.

Task<ApiEquifaxDTO> GetById30Valid(int id)

Validation: Returns null if the record is older than 30 days.

Location: Services/ApiEquifax/ApiEquifaxRepository.cs:29-42

Update

Updates an existing Equifax report.

Task<ApiEquifaxDTO> Update(ApiEquifaxDTO apiEquifax)

Request Structure

The request to Equifax follows this structure:

{
  "applicants": {
    "primaryConsumer": {
      "personalInformation": {
        "tipoDocumento": "C",
        "numeroDocumento": "1234567890"
      }
    }
  },
  "productData": {
    "productName": "[Configured Product]",
    "billTo": "[Account Info]",
    "customer": "[Customer Code]"
  }
}

HTTP Configuration

The service configures HTTP headers for optimal compatibility:

Authorization: Bearer {token}
Accept: */*
User-Agent: ModernaSatelite/1.0.0
Accept-Encoding: gzip, deflate, br
Content-Type: application/json

Error Handling

Success Response

Status Code: 200 OK

Returns a complete ReporteCrediticio object.

Error Response

Throws an exception with detailed error information:

Equifax {StatusCode} {ReasonPhrase}. CT-Res: {ContentType}; Body: {ResponseBody}

Common Errors

• 401 Unauthorized: Invalid or expired OAuth token
• 404 Not Found: No credit report found for the identification
• 500 Internal Server Error: Equifax service unavailable

Data Persistence

Equifax reports are stored in the ind_ac_apiequifax database table with:

• Automatic timestamp tracking (CreatedAt, UpdatedAt)
• 30-day validity period for cached data
• Full report data in JSON format

GraphQL Integration Example

While the service is primarily used internally, you can access Equifax data through client-related queries:

query GetClientCreditReport($documento: String!) {
  getClientByDocument(documento: $documento) {
    # Equifax data is embedded in client response
    idApiEquifax
    # Related credit information
  }
}

Best Practices

1. Cache Utilization: Use GetById30Valid to leverage cached reports within the 30-day window
2. Token Management: The OAuth token is automatically managed - no manual refresh needed
3. Error Handling: Always implement try-catch blocks when calling Equifax services
4. Rate Limiting: Be mindful of API call frequency to avoid rate limits
5. Data Privacy: Equifax data contains sensitive financial information - ensure proper access controls

Configuration

Equifax service requires the following configuration in appsettings.json:

{
  "EquifaxService": {
    "BaseUrl": "https://api.equifax.com.ec",
    "Endpoints": {
      "Reporte": "/v1/reporte-crediticio"
    },
    "ProductData": {
      "ProductName": "[Your Product]",
      "BillTo": "[Account]",
      "Customer": "[Customer Code]"
    }
  }
}

Performance Considerations

• First request: ~2-5 seconds (includes OAuth token acquisition)
• Cached request: Less than 100ms (database retrieval)
• Token refresh: Automatic, transparent to callers
• Response compression: Enabled via Accept-Encoding headers