Itaú for Developers - Complete tutorial: Update the Itaú API certificate chain

Introduction

Itaú is updating the digital certificate chain used in its APIs.

If your company consumes Itaú APIs, it is important to update your environment's certificate configuration within the informed deadline to keep communication working normally.

Certificate chain update flow

Follow the path below according to the result of each check.

Step or decision Requires attention Fix required Success

Start

Affected endpoint?

No action required

Yes

Identify the new URL

Download the new CA bundle

Configure outbound firewallCurrent and new IPs

Import the new certificate chain

Validate in the application's real environment

HTTP 200?

Review certificatesFirewall, proxy and network

After fixing, go back to Validate in the application's real environment.

Yes

Environment ready

Update the application URL

Run functional tests

Update completed

What do you need to do?

Check the migration schedule and update your environment's certificate chain before the date corresponding to the endpoint used by your integration.

Important

Applications that do not recognize the new certificate chain may experience connection failures after the migration.

Check the full schedule and download the certificate bundle.

Schedule and downloads

Who needs to perform the update?

You need to perform this update if your solution consumes Itaú APIs, including integrations for:

Pix;
Bank slips (boletos);
Payments;
Open Finance;
Foreign exchange;
Other APIs provided by Itaú.

Which URLs are impacted?

Depending on the impacted address, use the corresponding validation URL:


  https://secure.gateway.api.itau/sandbox/ca-validation
  https://api.gateway.itau.com.br/sandbox/ca-validation
  https://api-bin.gateway.itau.com.br/sandbox/ca-validation

What can happen if the update is not performed?

After each endpoint is migrated, applications that do not recognize the new certificate chain may experience TLS/SSL connection failures. The most common errors are:

SSL certificate verify failed
PKIX path building failed
unable to get local issuer certificate
CERT_UNTRUSTED
The remote certificate is invalid

If this happens, communication with the APIs may be interrupted until the update is completed.

Update the CA

Choose the option in the table of contents that best matches your infrastructure and follow the corresponding tutorial.

Windows Server

Below we describe the procedures to import the new certificate chain in the Windows Server environment. There are three methods available: via the graphical interface (MMC), via PowerShell and via certutil. Choose the one that best fits your scenario.

Note

All procedures below require Administrator privileges. Make sure to run the tools with elevated permissions ("Run as Administrator").

Import via MMC

This is the recommended graphical method for those who prefer a visual interface.

Open MMC and add the Certificates Snap-in

Press Win + R, type mmc and press Enter.
In the top menu, click File ? Add/Remove Snap-in... (or Ctrl + M).
In the list on the left, select Certificates and click Add >.
Select Computer account and click Next.
Keep Local computer and click Finish.
Click OK. The tree will show the node Certificates (Local Computer).

Import the new Root CA

Expand Certificates (Local Computer) ? Trusted Root Certification Authorities ? Certificates.
Right-click the folder Certificates and select All Tasks ? Import....
On the welcome screen, click Next.
Click Browse... and select the file root-ca.crt (extracted from the Certificate Bundle from the Itaú Developer Portal).
Confirm that the store is Trusted Root Certification Authorities.
Click Next and Finish.

Import the Intermediate Certificate

Expand Certificates (Local Computer) ? Intermediate Certification Authorities ? Certificates.
Right-click the folder Certificates and select All Tasks ? Import....
Repeat the previous process, but select the file intermediate-ca.crt.
Confirm that the store is Intermediate Certification Authorities and finish.

Attention

Do not remove the previous chain's certificates during the transition period. Both chains must coexist until Itaú officially announces the decommissioning of the old chain.

Import via PowerShell

Open PowerShell as Administrator.

Import the Root CA

powershell

Import-Certificate `
    -FilePath "C:\path\to\root-ca.crt" `
    -CertStoreLocation Cert:\LocalMachine\Root

Import the Intermediate Certificate

powershell

Import-Certificate `
    -FilePath "C:\path\to\intermediate-ca.crt" `
    -CertStoreLocation Cert:\LocalMachine\CA

Note

The parameter Cert:\LocalMachine\Root corresponds to "Trusted Root Certification Authorities" and Cert:\LocalMachine\CA to "Intermediate Certification Authorities".

Verify the import

To confirm the presence of the new Root CA:

powershell

Get-ChildItem -Path Cert:\LocalMachine\Root | `
    Where-Object { $_.Subject -like "*Itau*" } | `
    Format-List Subject, Thumbprint, NotBefore, NotAfter

For the intermediate certificate:

powershell

Get-ChildItem -Path Cert:\LocalMachine\CA | `
    Where-Object { $_.Subject -like "*Itau*" } | `
    Format-List Subject, Thumbprint, NotBefore, NotAfter

Example of expected output:

Subject    : CN=Itau Intermediate CA, O=Itau Unibanco S.A., C=BR
Thumbprint : A1B2C3D4E5F6...
NotBefore  : 01/01/2025 00:00:00
NotAfter   : 12/31/2030 23:59:59

Note

Replace "*Itau*" with the exact Common Name (CN) present in the certificates, if needed.

Import via certutil

The certutil is a native Windows command-line tool. Open the Command Prompt as Administrator.

Import the Root CA

cmd

certutil -addstore "Root" "C:\path\to\root-ca.crt"

Import the Intermediate Certificate

cmd

certutil -addstore "CA" "C:\path\to\intermediate-ca.crt"

Expected output:

Root "Trusted Root Certification Authorities"
The certificate "CN=..." was added to the store.
CertUtil: -addstore command completed successfully.

Note

The store names (Root and CA) are Windows standards and do not depend on the operating system language.

Validation on Windows

After the import, validate that the new chain is being recognized.

Option A — Test with curl

cmd

curl -v https://sts.itau.com.br

Look for:

* SSL connection using TLSv1.2 / ...
* Server certificate:
*   subject: CN=sts.itau.com.br; ...
*   issuer: CN=Itau Intermediate CA; ...
*   SSL certificate verify ok.

Option B — Test with Invoke-WebRequest

powershell

try {
    $response = Invoke-WebRequest -Uri "https://sts.itau.com.br" -UseBasicParsing
    Write-Host "Status: $($response.StatusCode) - TLS connection successful!" -ForegroundColor Green
} catch {
    Write-Host "Connection error: $($_.Exception.Message)" -ForegroundColor Red
}

Option C — Check the chain with certutil

cmd

certutil -verify -urlfetch "C:\path\to\intermediate-ca.crt"

Common errors on Windows

Error	Probable cause	Solution
`CERT_E_UNTRUSTEDROOT`	The Root CA was not imported into the correct store or the import failed silently.	Re-import the `root-ca.crt` in Trusted Root and check with `Get-ChildItem Cert:\LocalMachine\Root`.
`SEC_E_UNTRUSTED_ROOT` / `0x80090325`	The intermediate was imported, but the Root CA is missing.	Import both: the Root CA in `Root` and the intermediate in `CA`.
`Access is denied`	Terminal without Administrator privileges.	Reopen with Run as Administrator.
`The specified file was not found`	Path of the `.crt` is incorrect or the file was not extracted from the bundle.	Check the full path and the bundle extraction.
`Cannot find object or property`	Certificate imported into Current User instead of Local Computer.	In MMC, select Computer account. In PowerShell, use `Cert:\LocalMachine\...`.
`The underlying connection was closed`	Incompatible TLS or truststore does not recognize the chain.	Force TLS 1.2 with `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12`.
`A required certificate is not within its validity period`	System clock out of date.	Sync via NTP: `w32tm /resync /force`.

Attention

After importing the certificates, you may need to restart the application services (IIS, Apache, .NET services, etc.) so they recognize the new chain.

Linux (Ubuntu/Debian and RHEL/CentOS)

Linux distributions use different mechanisms to manage the system trust store. Below are the procedures for the two main families.

Note

All commands must be run as root or with sudo.

Ubuntu/Debian — system trust store

Step 1 — Copy the certificates

bash

sudo cp root-ca.crt /usr/local/share/ca-certificates/itau-root-ca.crt
sudo cp intermediate-ca.crt /usr/local/share/ca-certificates/itau-intermediate-ca.crt

Note

The directory only accepts PEM files with the extension .crt. Convert DER formats with openssl x509 -inform DER -in root-ca.der -out root-ca.crt.

Step 2 — Update the trust store

bash

sudo update-ca-certificates

Expected output:

Updating certificates in /etc/ssl/certs...
2 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

Step 3 — Confirm the presence

bash

ls -la /etc/ssl/certs/ | grep -i itau

Attention

Do not remove the previous chain's certificates during the transition period.

RHEL/CentOS/Amazon Linux — system trust store

Step 1 — Enable dynamic management (if needed)

bash

sudo update-ca-trust enable

Step 2 — Copy the certificates to the anchors

bash

sudo cp root-ca.crt /etc/pki/ca-trust/source/anchors/itau-root-ca.crt
sudo cp intermediate-ca.crt /etc/pki/ca-trust/source/anchors/itau-intermediate-ca.crt

Step 3 — Update the trust store

bash

sudo update-ca-trust extract

Note

Unlike Ubuntu/Debian, the command does not display detailed output. The absence of errors indicates success.

Step 4 — Confirm the presence

bash

trust list | grep -i -A 3 "itau"

Validation on Linux

Test 1 — curl

bash

curl -v https://sts.itau.com.br

Look for SSL certificate verify ok. in the output.

Test 2 — openssl s_client

bash

openssl s_client -connect sts.itau.com.br:443 -CApath /etc/ssl/certs/

For RHEL/CentOS use the consolidated bundle:

bash

openssl s_client -connect sts.itau.com.br:443 -CAfile /etc/pki/tls/certs/ca-bundle.crt

The return Verify return code: 0 (ok) confirms that the chain is trusted.

Common errors on Linux

Error	Probable cause	Solution
`curl: (60) SSL certificate problem: unable to get local issuer certificate`	The Root CA was not imported or the update command was not run.	Copy the certificates and run `update-ca-certificates` (Debian/Ubuntu) or `update-ca-trust extract` (RHEL/CentOS).
`curl: (77) error setting certificate verify locations`	Incorrect bundle path or `ca-certificates` package missing (e.g., minimal containers).	Install `ca-certificates` and re-import the certificates.
`Verify return code: 20`	OpenSSL did not find the Root CA in the given path.	Use the correct `-CApath`/`-CAfile` for the distribution.
`Verify return code: 2`	Intermediate certificate missing or corrupted.	Re-import the intermediate and validate with `openssl x509 -in intermediate-ca.crt -text -noout`.
0 added in `update-ca-certificates`	Extension other than `.crt`, DER format or wrong directory.	Confirm the extension `.crt` and PEM format; copy to `/usr/local/share/ca-certificates/`.
`Permission denied`	Command without superuser privileges.	Prefix with `sudo` or use `sudo su -`.
`certificate verify failed` in Python/Java/Node apps	Application uses its own truststore (certifi, cacerts) instead of the OS one.	Configure `REQUESTS_CA_BUNDLE`, `keytool -importcert` or `NODE_EXTRA_CA_CERTS` depending on the language.

Attention

After updating the trust store, restart the application services. TLS connections already established will not be affected until they are renewed.

Microsoft Azure

The Azure platform offers several ways to manage custom CA certificates, depending on the service used.

Attention

All procedures must be completed by September 15, 2026. During the transition, keep the current chain together with the new one.

Azure App Service

Allows adding custom CA certificates to the truststore via Portal or CLI.

Upload via CLI

bash

az webapp config ssl upload \
  --certificate-file ./root-ca.crt \
  --name <APP_SERVICE_NAME> \
  --resource-group <RESOURCE_GROUP>

WEBSITE_LOAD_ROOT_CERTIFICATES variable

Set the variable with the thumbprints of the imported certificates so the runtime loads them into the truststore.

bash

az webapp config appsettings set \
  --name <APP_SERVICE_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --settings WEBSITE_LOAD_ROOT_CERTIFICATES="<THUMBPRINT_ROOT>,<THUMBPRINT_INTERMEDIATE>"

Note

To load all public certificates, use the value *. In production, prefer listing the thumbprints explicitly.

Azure API Management

APIM uses CA certificates to validate TLS connections with backends.

bash

az apim certificate create \
  --resource-group <RESOURCE_GROUP> \
  --service-name <APIM_NAME> \
  --certificate-id "itau-root-ca-new" \
  --data @root-ca.crt

Note

After the upload, APIM may take up to 15 minutes to propagate the certificates. Plan outside critical windows.

Azure Key Vault

Recommended solution for centralized management, allowing multiple applications to reference the same certificates.

bash

az keyvault certificate import \
  --vault-name <KEY_VAULT_NAME> \
  --name "itau-root-ca-2026" \
  --file ./root-ca.crt

Note

With Key Vault you centralize management and rotate certificates without redeploying the applications.

Azure Virtual Machines

For VMs, the procedure follows that of the underlying operating system (Windows or Linux).

Quick summary for Linux on an Azure VM:

bash

sudo cp root-ca.crt /usr/local/share/ca-certificates/itau-root-ca.crt
sudo cp intermediate-ca.crt /usr/local/share/ca-certificates/itau-intermediate-ca.crt
sudo update-ca-certificates
curl -v https://sts.itau.com.br

Quick summary for Windows on an Azure VM:

powershell

Import-Certificate -FilePath "C:\certs\root-ca.crt" -CertStoreLocation "Cert:\LocalMachine\Root"
Import-Certificate -FilePath "C:\certs\intermediate-ca.crt" -CertStoreLocation "Cert:\LocalMachine\CA"
Invoke-WebRequest -Uri "https://sts.itau.com.br" -UseBasicParsing

Allowing IPs in the Azure NSG

If you use Network Security Groups to control outbound traffic, allow the new IP ranges.

bash

az network nsg rule create \
  --resource-group <RESOURCE_GROUP> \
  --nsg-name <NSG_NAME> \
  --name "Allow-Itau-API-Gateway" \
  --priority 100 --direction Outbound --access Allow --protocol Tcp \
  --destination-address-prefixes "3.44.192.200/29" \
  --destination-port-ranges 443 \
  --source-address-prefixes "*" --source-port-ranges "*"

Attention

Keep the rules for the old IPs active during the transition. Remove them only after confirming the migration of all endpoints (after 09/15/2026).

Common errors on Azure

Error	Service	Probable cause	Solution
`WEBSITE_FAILED_TO_LOAD_CERTIFICATE`	App Service	Incorrect thumbprint or certificate not found.	Check the thumbprints (without `:`) and restart the App Service.
`SSL connection could not be established`	API Management	CA certificates not imported or backend not configured.	Import root and intermediate and check the backend.
`SecretNotFound / CertificateNotFound`	Key Vault	Identity without permission or incorrect name.	Use `az keyvault set-policy` (get, list) and check the name.
`AuthorizationFailed - NSG Rule`	VNet / NSG	Outbound rule blocking the new IPs.	Allow TCP/443 to `3.44.192.200/29` and `18.96.65.56/29`.
`CERT_UNTRUSTED`	App Service / VM	New Root CA missing from the truststore.	Import `root-ca.crt` into the appropriate truststore.
`Connection timed out`	Any with NSG/Firewall	Firewall/NSG blocking outbound traffic.	Check NSG, Azure Firewall and UDR; allow port 443.

Amazon Web Services (AWS)

AWS offers several services for certificate management and integration with external APIs.

Attention

All procedures must be completed by September 15, 2026. Download the Certificate Bundle from the Itaú Developer Portal before starting.

AWS API Gateway

It can use custom CA certificates to validate TLS connections with backends and for mTLS.

Updating truststores in S3 for mutual TLS

bash

aws s3 cp s3://<BUCKET>/truststore.pem ./truststore-current.pem
cat root-ca.crt >> truststore-current.pem
cat intermediate-ca.crt >> truststore-current.pem
aws s3 cp ./truststore-current.pem s3://<BUCKET>/truststore.pem

Note

The truststore in S3 must contain all CA certificates in concatenated PEM. Keep the old and the new ones during the transition.

AWS Certificate Manager (ACM)

bash

aws acm import-certificate \
  --certificate fileb://root-ca.crt \
  --region <REGION> \
  --tags Key=Name,Value=itau-root-ca-2026

Attention

ACM does not manage truststores for outbound connections. To trust the new Itaú CA, update the truststore in the application itself or in the OS of the instance/container.

AWS Lambda + Layers

Lambda functions do not have direct access to the OS. Use Lambda Layers + environment variables.

bash

mkdir -p itau-ca-layer/certs
cp root-ca.crt intermediate-ca.crt itau-ca-layer/certs/
cat root-ca.crt intermediate-ca.crt > itau-ca-layer/certs/itau-ca-bundle.crt
cd itau-ca-layer && zip -r ../itau-ca-layer.zip . && cd ..
aws lambda publish-layer-version --layer-name itau-ca-certificates \
  --zip-file fileb://itau-ca-layer.zip \
  --compatible-runtimes python3.12 nodejs20.x java21 --region <REGION>

Set the function's environment variables:

SSL_CERT_FILE=/opt/certs/itau-ca-bundle.crt
NODE_EXTRA_CA_CERTS=/opt/certs/itau-ca-bundle.crt
REQUESTS_CA_BUNDLE=/opt/certs/itau-ca-bundle.crt

Note

The Layer files are located at /opt/ in the Lambda environment.

Amazon ECS / EKS

Include the certificates in the Docker image or via ConfigMap/Secret in Kubernetes.

dockerfile

FROM python:3.12-slim
COPY root-ca.crt /usr/local/share/ca-certificates/itau-root-ca.crt
COPY intermediate-ca.crt /usr/local/share/ca-certificates/itau-intermediate-ca.crt
RUN update-ca-certificates
ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

Via ConfigMap on EKS:

bash

kubectl create configmap itau-ca-certificates \
  --from-file=itau-ca-bundle.crt=./itau-ca-bundle.crt \
  --namespace <NAMESPACE>

Security Groups and NACLs

bash

aws ec2 authorize-security-group-egress \
  --group-id $SG_ID \
  --ip-permissions IpProtocol=tcp,FromPort=443,ToPort=443,IpRanges='[{CidrIp=3.44.192.200/29}]'

Attention

NACLs are stateless — create outbound and inbound rules (ephemeral ports 1024-65535). Security Groups are stateful and do not require return rules.

Common errors on AWS

Error	Service	Probable cause	Solution
`CERTIFICATE_VERIFY_FAILED`	Lambda	New Root CA missing from the function's bundle.	Create a Layer and set `SSL_CERT_FILE`/`NODE_EXTRA_CA_CERTS`.
`unable to verify the first certificate`	ECS / EKS	Container without the new chain in the truststore.	Add `COPY` + `update-ca-certificates` in the Dockerfile or mount it via ConfigMap.
`Connection timed out`	EC2 / ECS / Lambda	SG or NACL blocking outbound traffic.	Allow TCP/443 to the new ranges; in the NACL, add ephemeral inbound rules.
`PKIX path building failed`	ECS / EKS (Java)	Java truststore (cacerts) without the new Root CA.	Use `keytool -importcert` into `cacerts`.
`self signed certificate in certificate chain`	Lambda (Node.js)	`NODE_EXTRA_CA_CERTS` missing or nonexistent path.	Attach the Layer and set `NODE_EXTRA_CA_CERTS=/opt/certs/itau-ca-bundle.crt`.
`SSLHandshakeException: No trusted certificate found`	API Gateway + VPC Link	Backend behind the NLB does not recognize the new chain.	Update the truststore on the backend (EC2/ECS).

SaaS platforms

SaaS platforms abstract the infrastructure, but integrations with external APIs such as Itaú's may require specific certificate and network settings.

Attention

In SaaS you often do not have direct access to the OS or to the truststore. The procedures focus on the configuration options available on each platform.

Shopify

Shopify automatically manages the stores' TLS certificates. For standard operation, no action is required.

For custom apps that call Itaú APIs:

Apps on Shopify infrastructure: it is not possible to customize the truststore; if needed, contact Shopify Partners Support.
Self-hosted apps: follow the Linux/Windows/Docker instructions to update the server's truststore.

Update old callback URLs (api.itau.com.br) to the new ones (api.gateway.itau.com.br) before 09/15/2026.

Salesforce

Use Named Credentials to configure the integration and update the URL to the new endpoint.

Certificate and Key Management: import root-ca.crt and intermediate-ca.crt if the new CA is not automatically recognized;
Remote Site Settings: add the new endpoints (keeping the old ones during the transition);
CSP Trusted Sites: add the new domains to avoid blocks in Lightning components.

Test via Apex:

apex

HttpRequest req = new HttpRequest();
req.setEndpoint('https://sts.itau.com.br');
req.setMethod('GET');
Http http = new Http();
HttpResponse res = http.send(req);
System.debug('Status: ' + res.getStatusCode());

Online ERPs (SAP, TOTVS, Oracle)

SAP Business Technology Platform (BTP)

Configure the Destination with the new URL and import the certificates into Security ? Trust Configuration.

Note

If you use TrustAll=true, validation is skipped — a practice not recommended in production. Prefer TrustAll=false and import the chain.

TOTVS Protheus

In appserver.ini, point CACertFile to the bundle with the new chain:

ini

[SSLConfigure]
TLS12=1
TLS13=1
CACertFile=C:\TOTVS\certs\itau-ca-bundle.crt
VerifyPeer=1
VerifyDepth=5

Oracle Integration Cloud (OIC)

In Settings ? Certificates, upload root-ca.crt and intermediate-ca.crt as Trust Certificates and update the Connection.

Common errors on SaaS

Error	Platform	Probable cause	Solution
`UNABLE_TO_VERIFY_LEAF_SIGNATURE`	Shopify (Node.js app)	Server truststore without the new Root CA.	Update the truststore and set `NODE_EXTRA_CA_CERTS`.
`handshake_failure`	Salesforce (Apex)	New CA missing or URL not allowed.	Import it in Certificate and Key Management and add it in Remote Site Settings.
`PKIX path building failed`	SAP BTP	`TrustAll=false` without the imported chain.	Import it in Trust Configuration or via SAP Cloud Connector.
`SSL handshake error`	TOTVS Protheus	`CACertFile` does not point to the updated bundle.	Update the `CACertFile` and restart the AppServer.
`ORA-29024: Certificate validation failure`	Oracle Integration Cloud	Outdated Trust Certificates.	Upload the new chain in Settings ? Certificates.
`Timeout` when connecting	Any SaaS with IP restriction	Fixed outbound IPs cannot reach the new endpoints.	Check the platform's IP whitelisting; allow the new ranges.

Programming languages

Instructions by language, ordered by request volume. Start with the language your application uses.

Java (HttpURLConnection / Apache HttpClient)

Attention

This section covers more than 53% of all requests to Itaú APIs.

Import into the JVM truststore (keytool)

bash

keytool -importcert -alias itau-root-ca-new \
  -file root-ca.crt \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit -noprompt
keytool -importcert -alias itau-intermediate-new \
  -file intermediate-ca.crt \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit -noprompt

Note

The default password of the cacerts is changeit. Repeat for each Java installation (8, 11, 17, 21).

Custom truststore via system properties

bash

java \
  -Djavax.net.ssl.trustStore=/path/my-truststore.jks \
  -Djavax.net.ssl.trustStorePassword=myPassword \
  -jar my-application.jar

Verification

bash

keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit | grep -i itau

Common errors in Java

Error	Cause	Solution
`PKIX path building failed`	New Root CA missing from the truststore.	Import via `keytool -importcert`.
`handshake_failure`	Incompatible TLS protocol or missing intermediate.	Import the intermediate and use `-Dhttps.protocols=TLSv1.2`.
`Keystore was tampered with, or password was incorrect`	Incorrect cacerts password.	Use `changeit` or the password set by your team.

Go uses the OS trust store by default. For a custom tls.Config or scratch/distroless containers, load it programmatically.

rootCAs, _ := x509.SystemCertPool()
if rootCAs == nil { rootCAs = x509.NewCertPool() }
rootPEM, _ := os.ReadFile("certs/root-ca.crt")
rootCAs.AppendCertsFromPEM(rootPEM)
intPEM, _ := os.ReadFile("certs/intermediate-ca.crt")
rootCAs.AppendCertsFromPEM(intPEM)
tlsConfig := &tls.Config{RootCAs: rootCAs, MinVersion: tls.VersionTLS12}
client := &http.Client{Transport: &http.Transport{TLSClientConfig: tlsConfig}}

Common errors in Go

Error	Cause	Solution
`x509: certificate signed by unknown authority`	New Root CA missing from the pool.	Install it in the OS or use `AppendCertsFromPEM`.
`x509: certificate has expired or is not yet valid`	Expired certificate or incorrect clock.	Import the new certificates and sync the clock.
`net/http: TLS handshake timeout`	Firewall/proxy blocking 443.	Check the network rules.

JavaScript / Node.js

Via NODE_EXTRA_CA_CERTS (without changing code)

bash

cat root-ca.crt intermediate-ca.crt > itau-ca-bundle.pem
NODE_EXTRA_CA_CERTS=./itau-ca-bundle.pem node app.js

Programmatically via https.Agent

javascript

const https = require('node:https');
const tls = require('node:tls');
const fs = require('node:fs');
const rootCA = fs.readFileSync('certs/root-ca.crt');
const intCA = fs.readFileSync('certs/intermediate-ca.crt');
const agent = new https.Agent({ ca: [...tls.rootCertificates, rootCA, intCA] });

Never in production

NEVER use NODE_TLS_REJECT_UNAUTHORIZED=0 in production — it disables all certificate verification and exposes the application to man-in-the-middle attacks.

Common errors in Node.js

Error	Cause	Solution
`UNABLE_TO_VERIFY_LEAF_SIGNATURE`	Intermediate missing from the bundle.	Add the intermediate via `NODE_EXTRA_CA_CERTS` or `ca`.
`CERT_HAS_EXPIRED`	The old chain's certificate expired.	Update to the new certificates.
`SELF_SIGNED_CERT_IN_CHAIN`	Self-signed certificate in the chain (corporate proxy).	Check the files and MITM proxies.

Python (requests / urllib3)

Environment variables

bash

export REQUESTS_CA_BUNDLE=/path/itau-ca-bundle.pem
export SSL_CERT_FILE=/path/itau-ca-bundle.pem
python app.py

verify parameter

python

import requests
response = requests.get(
    "https://sts.itau.com.br",
    verify="/path/itau-ca-bundle.pem",
    timeout=10
)
print(response.status_code)

Common errors in Python

Error	Cause	Solution
`CERTIFICATE_VERIFY_FAILED`	New Root CA missing from the bundle/certifi.	Configure `REQUESTS_CA_BUNDLE` or `verify=`.
`unable to get local issuer certificate`	Intermediate missing.	Include `intermediate-ca.crt` in the PEM bundle.
`WRONG_VERSION_NUMBER`	TLS on a non-TLS port or incorrect proxy.	Use `https://` and check the proxies.

Java / Kotlin with OkHttp

OkHttp uses the JVM truststore by default. Pay special attention to CertificatePinner.

Certificate Pinning — updating the pins

Add the (SHA-256) pins of the new certificates before the migration, keeping the old ones during the transition.

bash

openssl x509 -in root-ca.crt -pubkey -noout | \
  openssl pkey -pubin -outform DER | \
  openssl dgst -sha256 -binary | base64

Attention

Always keep at least two pins (backup pin) to avoid accidental lockouts. Remove the old pins only after completing the migration.

Common errors in OkHttp

Error	Cause	Solution
`Certificate pinning failure!`	Pins do not match the new chain.	Add the SHA-256 pins of the new certificates.
`Trust anchor for certification path not found`	New Root CA missing from the truststore.	Import the certificates or configure `SSLSocketFactory`.
`Chain validation failed`	Incomplete chain.	Import root and intermediate.

C# / .NET

.NET uses the OS trust store by default. Programmatic import on Windows:

csharp

using var rootCert = new X509Certificate2("root-ca.crt");
using var rootStore = new X509Store(StoreName.Root, StoreLocation.LocalMachine);
rootStore.Open(OpenFlags.ReadWrite);
rootStore.Add(rootCert);
rootStore.Close();

Common errors in C# / .NET

Error	Cause	Solution
`The remote certificate is invalid`	New Root CA missing from the trust store.	Install it in the OS or use `ServerCertificateCustomValidationCallback`.
`The SSL connection could not be established`	Intermediate missing or incompatible TLS.	Include the intermediate; check TLS 1.2 support.
`certificate chain could not be built`	Incomplete chain.	Import root and intermediate into the trust store.

Delphi / Pascal

Most use Indy. Configure the TIdSSLIOHandlerSocketOpenSSL:

pascal

SSLHandler.SSLOptions.Method := sslvTLSv1_2;
SSLHandler.SSLOptions.RootCertFile := 'certs\itau-ca-bundle.pem';
SSLHandler.SSLOptions.VerifyMode := [sslvrfPeer];

Note

Indy components depend on the OpenSSL DLLs. Make sure they are accessible in the PATH or in the application folder (32-bit vs 64-bit).

Common errors in Delphi

Error	Cause	Solution
`certificate verify failed`	Root/intermediate missing from `RootCertFile`.	Point it to a bundle with root + intermediate.
`Could not load SSL library`	OpenSSL DLLs missing.	Ship the DLLs compatible with the application.
`Socket Error #10054`	Incompatible TLS or firewall.	Use `sslvTLSv1_2` and check the firewall.

Ruby

ruby

require 'net/http'
http = Net::HTTP.new('sts.itau.com.br', 443)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_PEER
http.ca_file = 'certs/itau-ca-bundle.pem'

Or set it globally: export SSL_CERT_FILE=/path/itau-ca-bundle.pem.

Common errors in Ruby

Error	Cause	Solution
`certificate verify failed (unable to get local issuer certificate)`	Root CA missing from the OS or `ca_file`.	Install it in the OS or configure `ca_file`.
`certificate has expired`	The old certificate expired.	Update to the new certificates.

PHP

Global configuration via php.ini

ini

openssl.cafile = /path/itau-ca-bundle.pem
curl.cainfo = /path/itau-ca-bundle.pem

Native cURL

php

curl_setopt_array($ch, [
    CURLOPT_URL => "https://sts.itau.com.br",
    CURLOPT_CAINFO => "certs/itau-ca-bundle.pem",
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1_2,
]);

Never in production

Do not disable verification: verify=false (Guzzle) or CURLOPT_SSL_VERIFYPEER=false.

Common errors in PHP

Error	Cause	Solution
`cURL error 60: unable to get local issuer certificate`	CA not found in the bundle.	Configure `curl.cainfo` or `CURLOPT_CAINFO`.
`cURL error 35: SSL connect error`	Incompatible TLS or missing intermediate.	Check OpenSSL/TLS 1.2 and include the intermediate.
`cURL error 51: subject name does not match`	Hostname does not match (MITM proxy).	Check the URL and corporate proxies.

Final note — applicable to all languages

Create the bundle by combining root-ca.crt and intermediate-ca.crt; keep both chains during the transition; validate with curl -v https://sts.itau.com.br; and never disable TLS verification in production.

Validation and testing

Before considering the migration complete, run a battery of tests to ensure the new chain was correctly installed and that the endpoints are reachable.

Attention

Run the tests from the same environment where the application runs in production. Testing from a local machine may mask network, firewall or truststore issues.

Test via cURL

Test URL

Depending on the impacted address, use the corresponding validation URL:

bash

https://secure.gateway.api.itau/sandbox/ca-validation
https://api.gateway.itau.com.br/sandbox/ca-validation
https://api-bin.gateway.itau.com.br/sandbox/ca-validation

cURL test

Before running the validation, generate an access token using your application credentials:

bash

curl --request POST \
  --url https://sts.itau.com.br/api/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id=<client-id>' \
  --data 'client_secret=<client-secret>'

After obtaining the token and making sure the new certificate chain was imported correctly, run the call below to validate communication with the environment:

bash

curl --request GET \
  --url <validation-url-used>'\
  --header 'x-itau-apikey: <client-id>' \
  --header 'x-itau-client-cert: <certificate>' \
  --header 'x-itau-correlationID: 123' \
  --header 'x-itau-flowID: 123'

Test via OpenSSL

bash

openssl s_client -connect sts.itau.com.br:443 -showcerts

The return Verify return code: 0 (ok) confirms that the full chain is trusted.

Common OpenSSL error codes

Code	Description	Action
2	`unable to get issuer certificate`	Root CA missing from the truststore.
20	`unable to get local issuer certificate`	Intermediate missing.
21	`unable to verify the first certificate`	Incomplete chain (the server did not send the intermediate).
10	`certificate has expired`	Expired certificate.
9	`certificate is not yet valid`	Incorrect system date.
19	`self-signed certificate in chain`	CA not recognized.

Test via PowerShell (Windows)

powershell

$endpoints = @(
    "https://secure.gateway.api.itau/healthcheckbalance",
    "https://api.gateway.itau.com.br/healthcheckbalance",
    "https://api-bin.gateway.itau.com.br/healthcheckbalance",
    "https://sts.itau.com.br"
)
foreach ($url in $endpoints) {
    try {
        $r = Invoke-WebRequest -Uri $url -UseBasicParsing -TimeoutSec 30
        Write-Host "[OK]   $url - HTTP $($r.StatusCode)" -ForegroundColor Green
    } catch {
        Write-Host "[FAIL] $url - $($_.Exception.Message)" -ForegroundColor Red
    }
}

Network connectivity test

DNS resolution

bash

dig sts.itau.com.br +short
dig secure.gateway.api.itau +short

Port connectivity (TCP 443)

bash

nc -zv sts.itau.com.br 443
nc -zv secure.gateway.api.itau 443

Note

If the new hostnames do not resolve, clear the DNS cache: ipconfig /flushdns (Windows) or sudo systemd-resolve --flush-caches (Linux).

Validation checklist

Before the migration

New chain (Root CA + Intermediate CA) obtained from the Developer Portal;
Certificates verified with openssl x509 -noout -text -in <file>.pem;
Truststore updated with the new certificates;
Backup of the previous truststore taken;
Firewall updated for 3.44.192.200/29 and 18.96.65.56/29;
Working DNS resolution for the new hostnames;
Endpoint URLs updated in the application;
Certificate pinning updated (if applicable);
Rollback plan documented.

During the migration

curl -v https://sts.itau.com.br returns a successful TLS handshake;
openssl s_client shows Verify return code: 0 (ok);
Healthchecks of the three endpoints return HTTP 200;
No TLS errors in the application logs;
End-to-end integration test executed successfully.

After the migration

TLS/SSL error monitoring enabled in production;
Latency and error metrics stable for at least 24 hours;
Alerts for future certificate expiration configured;
Old endpoints removed once decommissioned by Itaú;
Internal documentation updated;
Team informed about the completion.

Troubleshooting — Common errors and solutions

This section consolidates the most frequent errors during the update, with probable causes and solutions.

General error table

Error	Language / Environment	Probable cause	Solution
`CERTIFICATE_VERIFY_FAILED`	Python	Intermediate or Root CA missing from the bundle.	Update `certifi` or use `REQUESTS_CA_BUNDLE`.
`PKIX path building failed`	Java	JVM truststore without the new chain.	Import via `keytool` (password `changeit`) and restart.
`unable to get local issuer certificate`	OpenSSL / cURL	OS CA directory without the Root CA.	Copy the certificate and run `update-ca-certificates`/`update-ca-trust`.
`UNABLE_TO_VERIFY_LEAF_SIGNATURE`	Node.js	Cannot build the chain up to a trusted Root.	Configure `NODE_EXTRA_CA_CERTS`. Never use `NODE_TLS_REJECT_UNAUTHORIZED=0`.
`SEC_E_CERT_UNKNOWN`	Windows / .NET	Root not installed in the Certificate Store.	Use `Import-Certificate` in `Root` and `CA`.
`handshake_failure`	Java	Incompatible TLS protocol or cipher.	Java 8u261+; force `-Dhttps.protocols=TLSv1.2,TLSv1.3`.
`Connection refused / timed out`	Any (network)	Firewall blocking the new IPs.	Allow `3.44.192.200/29` and `18.96.65.56/29` on 443.
`certificate has expired`	Any	Old endpoint or incorrect clock.	Migrate to the new endpoint and sync via NTP.
`certificate pinning failure`	Mobile / OkHttp	The SHA-256 hash changed with the renewal.	Update the pins; consider pinning to the Root CA.
`DNS resolution failed`	Any (DNS)	New hostnames do not resolve.	Clear the DNS cache and check with `nslookup`.
`Trust anchor for certification path not found`	Android / Kotlin	Device without the new Root CA.	Use Network Security Config.
`ERR_CERT_AUTHORITY_INVALID`	Browsers	Proxy intercepting or Root not recognized.	Install the Root CA in the OS trust store.

Attention

Workarounds such as NODE_TLS_REJECT_UNAUTHORIZED=0, verify=False or SSLContext without validation completely disable verification and must never be used in production.

When to open a ticket with Itaú

Open a ticket when:

All network tests (DNS, TCP 443) work, but the TLS handshake fails;
The truststore is up to date, but the Verify return code still indicates an error;
The healthchecks return a persistent HTTP 5xx error;
There is a mismatch between the certificate received and the documented one;
The chain sent by the server is incomplete.

Need help during the migration? Talk to the team responsible for your segment.