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.

Integration flow

What is the mandatory sequence of operations?

The sequence is mandatory and cannot be changed:

1. AUTH — obtain the access_token (back end);
2. INIT — initialize the session and obtain the token and referenceId (back end);
3. MPI.load and MPI.init — load and initialize the script (front end);
4. MPI.updateCard — update the card number (front end);
5. ENROLL — authenticate the card (back end);
6. MPI.challenge — display the challenge to the cardholder, if required (front end);
7. VALIDATE — validate the authentication after the challenge (back end).

Warning: the API blocks out-of-order calls and repeated calls.

What does each status returned by ENROLL mean?

Can status 2 be returned in VALIDATE?

No. In the VALIDATE operation, only statuses 0 and 1 are returned. Status 2 is exclusive to ENROLL.

What should I do when ENROLL returns Status = 2?

Display the challenge to the cardholder using MPI.challenge(challengeData, order). After completion, the onValidationRequired callback is triggered with the TransactionId. Send that value to the back end and execute VALIDATE.

What should I do when ENROLL returns Status = 0?

Check the ECI returned in the response to decide whether to proceed with the transaction. A low ECI indicates that authentication was not performed and may result in a higher decline rate or fraud liability (chargeback) on the merchant's side. See the ECI Table for the correct interpretation of each value.

Front end and scripts

When should I call MPI.updateCard()?

Call MPI.updateCard() before sending the order to ENROLL. If the shopper changes cards during the same session, call it again before a new ENROLL to keep the session synchronized.

What is cardNumberReader?

It is a configuration callback of MPI.load. It is called by the script immediately before MPI.updateCard() and must return the card number as a string containing only digits.

Example:

cardNumberReader: function () {
    return document.getElementById("cardNumber").value.replace(/\D/g, "");
}

What is the parameter order in MPI.init()?

The signature is MPI.init(referenceId, token). The order is mandatory: first the referenceId, then the token returned by INIT. Reversing the parameters causes a silent failure — the onReady callback is not triggered and subsequent steps do not work.

What happens if I do not wait for the onReady callback before calling MPI.updateCard()?

The script may not be ready to process the update. Wait for the onReady callback before calling any method that depends on the initialized session.

What is MPIHelpers.getBrowserInfo() and why should I use it?

It is a utility from mpiHelpers.js that automatically collects the mandatory data of the BrowserInfo object from the shopper's browser: userAgent, screenWidth, screenHeight, colorDepth, timeZoneOffset, language, and javaEnabled. Use it to avoid manual collection and reduce errors.

Errors and diagnostics

What causes error 409?

Error 409 indicates an out-of-order call or a repeated call. Always follow the sequence: AUTH → INIT → ENROLL → VALIDATE.

What are the most common errors in the AUTH operation?

What do the Reason Codes mean?

For codes not listed, contact Cielo support.

Sandbox testing

How do I test the integration before going to production?

Use the test cards available in the documentation. Each card simulates a specific scenario:

See the full list at test cards.

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.