Migration guide: Itaú Shopline Boleto to Itaú API Boleto

Itaú will discontinue the Itaú Shopline boleto on December 15, 2025. After this date, the current solution will no longer work.

To continue using Itaú boleto payment services, you must migrate to the Itaú API boleto integration.

⚠️

Why do I need to migrate to Itaú API boleto?

Itaú announced the discontinuation of the Itaú Shopline integration starting December 15, 2025. After this date, the current solution will no longer work. To keep using Itaú boleto payment services, you must migrate to the Itaú API integration (Provider = "Itau3")

What are the main changes with the new Itaú API integration?

• Provider: Payment.Provider will be "Itau3" because this is a new integration;
• Reconciliation: In Itaú Shopline, reconciliation was done via API. With the new Itaú API integration, reconciliation will be through file exchange (via Nexxera VAN);
• Payment method: In Itaú Shopline, there was a redirect to an Itaú-hosted page where the shopper could choose to pay the boleto by barcode or by account debit (if an Itaú account holder). In the new integration, there is no redirect to the bank, and payment will always be by barcode.

What happens if I don’t migrate by the deadline?

If migration is not completed by December 15, 2025, your Itaú Shopline integration will stop working, and you will no longer be able to issue boletos through this platform.

Step-by-Step migration to Itaú API boleto

1. Obtain credentials from Itaú

The first step is to contact your Itaú account manager to get the following credentials:

2. Generate Dynamic Certificate

You need to log in to the Itaú for Developers portal to generate the dynamic certificate.

📘

To generate the dynamic certificate, access Itaú's documentation and go to Step 7 – How to generate the dynamic certificate.

Following Itaú's documentation, you can:

• Generate the dynamic certificate and download it from the portal;
• Create the dynamic certificate manually.

Dynamic certificate format

The dynamic certificate consists of the private key (KEY) and the public key (CSR) and follows this pattern:

• Example of private key – .key file that will be sent in Credencials.PrivateKey during the onboarding step:

-----BEGIN PRIVATE KEY-----
BEEGvwIBADANBgkqhkiG8w0BAQEFAASCBKkwggSlAgEAAoIBAQDFSQxt2LHLQhqI
1A/JJ2uBV+R4bKcM9RDi4T0S+EW4rYkmedgSnsfmuLQ8WlsWAH0O0cSlr5ozoFdU
Io97C/wD0zuNtmC/ekQeKItoef5/fVkePSbpwPZIQPGCEmDY8M/wkeI7zok6xF1B
BB1S3tqj/0Snkhtojnp6Eqdg2yZRTT6E2APVGoTt3rm7583ynAiqhbeBLbYm9jI4
Uq5PzOjs03MwS6J7P5lKWB1LsIt9dHAMAcGkcg2P3/sBk3qcOw80ZL5oI1h6mU3v
JZRS1w8UF/se95iByDl75d/utrHJeYpxNDGg0UZz7Fwpjr71IMBLHS36Po4jXqJ2
9EyM8gtlAgMBAAECggEAFaLuyYdH7H5J8bKsLofzuuI8TNbBtWKVIQTJ0XBIGTpy
/bTENTqTuuKL5ciVD8Mq8/qegftRwpK1sST/LmQAlhzO/bpAPw+2M8aHj4Q9nJbP
NMlJIL7IY+E3e2fvlitG6t/c+2kp1LefcJd2bdXCDdVbnrMf7WYe2Y99KtquB6Fr
KVXJL95I3rH5Ty7ts2cQ+ZgladSxYWaIvlfDhP7WjHunhN3c9q9lL8l1UIw4sK/L
MoEVj7Yu6HHgmAni6C/1iPuYK5l6h20n85geKqJdInpy0U24xFxV2Q/Xnx9PxInp
dL1wWdzZdcGyGTSnIWBvJcurB/8AfrBw3OztuVDKCwKBgQDyCdJ/tuTpNW7zczKZ
GyMrmrbD4HfoO6cJ0x0/zwRZ4i/sdVnAH9/9bf4rBWVPIzve/nfmHs1tw0IdQh08
PYxBDdVoglXCIFcLlTvFpc7xz4nxgLW6aBOElAyjz2WTtI6ZvaeJyu8vGnbXj5Fw
4lAUrD0MF9OrKJFmmqEK8ZWhPwKBgQDQqlvjMXGdd2eixJOfk0FbsZQKTI9v2a6A
G4ispWvGHMdSWqhOAj74VbZjQLNfXhqUtfseVGk+6ljWnA8UbYEix5TeW9oDYXuJ
SsqPxEDOwT+UaQIFWQw6nfQaBRrXLD2gTrhoiFrSmqaxZNbhMKkCcpeDwVPp6xQz
GoC3cDXGWwKBgQCKC+YeZ69J/+rnOaX7Q0oc/aIOOEHLl/JenSWKlkVSCrrwr8Hf
3Y5AmnKkEPDGYT8toY+7FYhveTWFQIcyK5yKIhy8/dFx5kYfWh98TGSq8Icp0hJU
XjX7oQFQkOLLiujmcRBUfAVNpVdw/PakHsAz+kTbV9+nOH0tuzXs6vs/uwKBgQCG
KiMurynYD2ApPa+VWL8bT9BZ1uQbDKGwaQO1zh6/oN1fzD6O+c63KZU9t+odFYqN
t3yhAbEx7Mf2JR1lCwuO6ziCyBgjOFiP6/DWA1+QEJzqtaHBAoJkZg7/c+zQEPgG
zNaxD4smAp3PTYEEBZ+FnVxiMLndm3K/cPj1+UX6JQKBgQDGO+AZusE6MimOlTQp
eyBF7o8fYRbk/fhbkEZX0oXZudVH2Su4qVfnvWU849JyMaJI1GiLmrMmTpjsOXLG
daNcC1oYlbXOr6jLtzo/In5YJzEXtUSSAV5OD3Wx0gG7BXynt+iumYIXayCvgbPQ
MyORpzbex1QxU9QgCDOPf+tMAt==
-----END PRIVATE KEY-----

• Example of public key – .csr file that will be sent in Credencials.PublicKey during the onboarding step:

-----BEGIN CERTIFICATE REQUEST-----
BEEGvjCCAaYCAQAweTEtMCsGA1UEAwwkRTA0MDhhZDAtZTkyOC00OTA3LTliN2Qt
N2QzMDhmM2U2ZjAyMRowGAYDVQQKDBFDT05TT1JDSU8gSU5URUdSQTESMBAGA1UE
BwwJU0FPIFBBVUxPMQswCQYDVQQIDAJTUDELMAkGA1UEBhMCQlIwggEiMA0GCSqG
SIb3DQEBAQUAA4IBDwAwggEKAoIBAQDFSQxt2LHLQhqI2A\/JJ2uBV+R4bKcM9RDi
4T0S+EW4rYkmedgSnsfmuLQ8WlsWAH0O0cSlr5ozoFdUIo97C\/wD0zuNtmC\/ekQe
KItoef5\/fVkePSbpwPZIQPGCEmDY8M\/wkeI7zok6xF1BBB1S3tqj\/0Snkhtojnp6
Eqdg2yZRTT6E2APVGoTt3rm7583ynAiqhbeBLbYm9jI4Uq5PzOjs03MwS6J7P5lK
WB1LsIt9dHAMAcGkcg2P3\/sBk3qcOw80ZL5oI1h6mU3vJZRS1w8UF\/se95iByDl7
5d\/utrHJeYpxNDGg0UZz7Fwpjr71IMBLHS36Po4jXqJ29EyM8gtlAgMBAAGgADAN
BgkqhkiG9w0BAQ0FAAOCAQEANSNma6rR5WGmzf\/1sjBcTSkVdxX\/jF2EAJgBkLi3
a\/+VQbKFZtecho+5Lh8INfW7L2ldytHJ7mUzez9aLbFmhbtRgJ+o\/gwJC0ATptFY
wxkQeTZhTx\/6nPb2G6RORNLgD1v9PRgF3iKKolLy0fDd2ZpWbmMD+h4ushYezYFu
OiMBDBvjOtVPuSF6EneaBViceeLUMqCYl+xrOt74zoGb7MDa3ukf7jhVoTXBE9V2
otognstT6zODxiD5kIadw13KZdA0ftRFoUg6939IIzH9VK+uyn71+R3lyP\/OD+av
8QBqAYqyGpjQk52j5T3Ua6LIUVUqIZSLPDLc0jkCuvgAZZ==
-----END CERTIFICATE REQUEST-----

The values above are for example only. You must generate your certificate in Itaú's portal.

⚠️

Save the PublicKey and PrivateKey credentials in a secure location, as they will be required for the annual certificate renewal process.

3. Onboarding of Itaú boleto API in Gateway de Pagamento

With the credentials in hand, you will perform the onboarding for the new boleto provider in Cielo's Gateway de Pagamento. To do this, you must send a request to the following endpoint:

Request

Header parameters

{
    "Provider": "Itau3",
    "PaymentType": "Boleto",
    "Credencials": {
        "PublicKey": "-----BEGIN CERTIFICATE REQUEST-----\\n...\\n-----END CERTIFICATE REQUEST-----",
        "PrivateKey": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----",
        "TokenTemporario": "eyJraWQiOi...f+tRUg==",
        "ClientId": "b0509ad1-e928-4907-9b7d-7d308f3e7g13",
        "Agencia": "2938",
        "Conta": "51122-9",
        "Carteira": "176",
        "Vencimento": "1"
    }
}

Observação sobre os parâmetros PublicKey e PrivateKey To ensure Postman (or a similar interface) correctly interprets line breaks in certificates or keys, use the escape character \r\n inside the string. This guarantees that the content is properly formatted during the request.

Parameters in the body

Response

• 200 OK: Onboarding completed successfully. Returns the provider's response object.
• 401 Unauthorized: Authentication failure in the headers.
• 400 Bad Request: Invalid data in the request body.

4. Configure the new provider in the request to Gateway de Pagamento

In the integration of the boleto creation request to the Gateway de Pagamento, change the value of Payment.Provider to Itau3.

5. Configure automatic boleto reconciliation

With Itaú Shopline, reconciliation was done via API directly with Itaú. In the integration with Itaú boleto API, reconciliation will be file-based and configured with the partner van Nexxera.

📘

See the article How boleto reconciliation works for a step-by-step guide to configuring file-based reconciliation.

In the file-based reconciliation model, automatic reconciliation of paid boletos will be maintained.