FAQ — New MPI Cielo integration

Frequently asked questions about the new Cielo MPI (V3) integration and the 3DS authentication protocol.

---

About the product

What is the new MPI Cielo (V3)?

MPI V3 is the new integration model for the Cielo 3DS authentication plugin. It operates exclusively in the server-to-server model: the merchant controls all API calls on the back end, including displaying the challenge to the cardholder when required.

---

Does MPI V3 change the 3DS protocol version?

No. MPI V3 is an evolution of the integration plugin, not the protocol. The 3DS protocol versions remain the same:

---

Who can use MPI V3?

MPI V3 is exclusive to clients with PCI DSS certification who have the 3DS product enabled at Cielo.

---

About migration

Do I need to migrate to the new MPI Cielo V3? Does the V2 integration continue to work?

The V2 integration will be discontinued. Migration to MPI V3 is mandatory for all merchants using 3DS authentication. Follow the deadline provided by Cielo to avoid interruption in payment processing.

---

Does migration to MPI Cielo V3 affect my end clients?

Not directly. The cardholder experience remains the same: the 3DS challenge continues to be displayed when required, with no visual or behavioral change for the shopper. What changes is the implementation on the merchant's back end and front end.

---

Do I need to request new credentials to use MPI Cielo V3?

No. The credentials (ClientId and ClientSecret) used to generate the access_token are the same. What changes is the AUTH endpoint: from /v2/auth/token to /v3/auth/token.

---

Can I run MPI V2 and V3 in parallel during migration?

Running both models simultaneously for the same order is not recommended. The scripts are incompatible with each other. Plan the migration as a complete replacement: remove the V2 scripts and classes and implement the V3 flow in full.

---

What happens to in-progress transactions during the version switch?

Transactions initiated with V2 must be completed with V2. Do not validate with V3 an authentication that was initiated with V2. Plan the V3 activation during a low-volume period to minimize the impact.

---

How much development effort does the migration require?

It depends on the current implementation. In general:

• Front end: remove inputs with bpmpi_* classes, replace the scripts, and implement initialization via MPI.load() and MPI.init().
• Back end: move the access_token generation and the ENROLL and VALIDATE calls to the server, if they are not already there. Update the AUTH endpoint.

The migration involves a paradigm shift (from front end to server-to-server). Plan time for development, testing, and certification.

---

Environment and configuration

What is the difference between sandbox and production?

The sandbox is the testing environment. Use it to validate the integration before going to production. Production transactions are real, incur costs, and may result in penalties from card brands and issuers.

---

Where do I find the sandbox and production endpoints?

---

Which JavaScript script should I include on the checkout page?

Include the two scripts below in the corresponding environment:

• mpi.js — responsible for session initialization, card update, and challenge display;
• mpiHelpers.js — provides utilities such as getBrowserInfo and the order builder.

See Step 1 – Prepare the front end for the full URLs.

---

Tokens and authentication

How to generate the ClientId and ClientSecret credentials?
The credentials are generated through the Portal E-commerce. Learn more at: How to generate the 3DS credential?

---

What is the difference between access_token and token?

They are two distinct tokens with different purposes:

Important: never expose the access_token on the front end.

---

How long is the access_token valid?

The access_token is valid for 20 minutes (1,200 seconds) in production. If it expires before the sequence is completed, subsequent calls will return 401. In that case, generate a new access_token and restart the flow from AUTH.

To avoid this scenario, generate a new access_token for each purchase session and monitor the expires_in field in the AUTH response.

---

What should I do when I receive error 401?

Regenerate the access_token by calling the AUTH operation again and restart the flow.

---

Next steps and related documentation

After completing authentication with Status = 1, send the data returned in the Authentication field to the authorization step via Payment.ExternalAuthentication.

For more details, see:

• 3DS Authentication — MPI V3;
• 3DS test cards;
• ECI Table.