Checkout Error Messages and Their Meaning

Checkout Error Messages and Their Meaning

While using the Carta del Docente widget during checkout, customers may encounter various error messages. These messages are displayed directly in the checkout interface and are intended to guide the user towards a correct resolution of the problem.

Error: “The Carta del Docente service is currently unavailable”

This is the main error message that completely blocks the use of the service.

1. What it means: The app does not have an active license to function on your store.
2. When it appears:
   • When the premium license has expired.
   • When the license has been cancelled.
   • When a valid license key has never been entered.
3. What the customer sees: The widget is visible, but upon attempting to validate a code or proceed with the order, this message appears and the checkout is blocked.
4. Actions for the merchant:
   1. Access the Carta del Docente app in your Shopify admin.
   2. Go to the “License & Premium Support” section.
   3. Enter a new valid license key or subscribe to a plan.
   4. Ensure that the “Enable widget” toggle in Shopify’s checkout settings is active (ON).

Note: This block is an automatic, multi-level protection. Even if you, as a merchant, forget to manually disable the widget in the checkout settings, the validation function will still block orders, preventing unauthorized transactions.

Error: “Certificate not configured” or “Certificate not found”

This error occurs when the app attempts to validate a real voucher (not in sandbox mode) but cannot find the certificate required for communication with the ministerial servers.

1. What it means: The app is configured to use the production (“Live”) environment, but the .pem certificate file has not been uploaded or the saved path is no longer valid.
2. When it appears: When a customer enters a code in the checkout and sandbox mode is deactivated in the app settings.
3. Actions for the merchant:
   1. Go to the “Certificate” section of the app.
   2. Upload the .pem certificate file you obtained from the ministerial portal.
   3. Enter the password associated with the certificate.
   4. Click the “Test Connection” button to verify that the certificate is working correctly.
   5. Ensure that “Sandbox Mode” is deactivated if you intend to accept real vouchers.

Error: “Invalid voucher” (or specific messages from the API)

These are errors that come directly from the Ministry of Education’s verification system and indicate a problem with the voucher code entered by the customer.

1. What it means: The entered code was not recognized as valid by the ministerial service.
2. Possible causes:
   • The code was typed incorrectly.
   • The voucher has already been used.
   • The voucher has expired.
   • The voucher is not enabled for the type of products in the cart (e.g., attempting to purchase hardware with a voucher valid only for books).
   • Temporary connection issue with ministerial servers.
3. Actions for the customer:
   1. Check that the voucher code has been entered correctly.
   2. Verify the status and remaining balance of their voucher on the “Carta del Docente” portal.
   3. Ensure that the products in the cart are compatible with the scope of use of their voucher.
   4. If the problem persists, contact the Carta del Docente portal support.

Error: “Insufficient voucher amount”

This message is not a blocking error, but an important notification.

1. What it means: The amount of the Carta del Docente voucher entered is less than the order total.
2. What happens: The widget will apply a discount equal to the voucher amount. The customer will need to pay the remaining difference using another standard payment method (e.g., credit card, PayPal) during the normal Shopify checkout flow.
3. Customer experience: The checkout is NOT blocked. After applying the voucher, the customer proceeds normally to the next step to pay the rest of the amount.

Widget not visible in checkout

In this case, there is no error message, but the widget simply does not appear.

1. Possible causes:
   • The “Enable widget” toggle in Shopify’s checkout settings is deactivated (OFF).
   • The app has been uninstalled.
   • A checkout draft is being viewed, not the live version.
2. Actions for the merchant:
   1. Go to Settings → Checkout in your Shopify admin.
   2. Scroll down to the “Checkout extensions” section.
   3. Find the “Carta del Docente” widget and ensure the toggle is active (ON).
   4. Publish the changes if you were editing a draft.