Voucher Validation and Confirmation Flow

Voucher Validation and Confirmation Flow

The validation process for a Carta del Docente voucher in your Shopify store follows a precise sequence of steps, from the moment the customer enters the code into the widget until the final order confirmation. Here is a detailed technical explanation of each phase.

1. Code Entry in the Checkout Widget

During order checkout, the customer finds a dedicated field to enter the Carta del Docente voucher code. This widget is a Shopify checkout extension that is displayed only if the app has been correctly configured by the merchant.

Note: The app is not a payment method. It is a tool that, after validating the code, applies a discount to the order total, allowing the customer to then pay the difference using standard payment methods.

2. Validation Request (Check) to the Backend

When the customer enters the code and proceeds, the widget sends a request to the app’s backend. This request contains two essential pieces of information:

• The codiceVoucher (the alphanumeric voucher code).
• The total amount of the cart intended to be paid with the voucher.

The backend receives this request and initiates the technical validation process.

3. Preliminary Backend Checks

Before contacting the ministerial APIs, the app performs several mandatory checks:

1. Configuration Verification: Checks that a valid certificate has been uploaded for the store (in production mode) or that sandbox mode is active for testing.
2. Billing Status Check: The app verifies the store’s subscription status. Validation is blocked if:
   • The trial period is expired.
   • The subscription is cancelled.

   In these cases, a clear error is returned, prompting the merchant to activate or reactivate a subscription.

3. Certificate Preparation: Depending on the mode, the correct certificate is selected:
   • In sandbox: uses a pre-configured demo certificate.
   • In production: uses the .pem certificate uploaded by the merchant in the app settings. The certificate is read from the filesystem and “cleaned” by removing unnecessary metadata (such as “Bag Attributes”) to prepare it for the SOAP call.

4. Call to Ministerial SOAP APIs

With all checks passed, the app directly contacts the servers of the Ministry of Education via a SOAP client.

1. Endpoint: The destination URL changes based on the mode:
   • Sandbox: https://wstest.cartadeldocente.istruzione.it/VerificaVoucherDocWEB/VerificaVoucher
   • Production: https://ws.cartadeldocente.istruzione.it/VerificaVoucherDocWEB/VerificaVoucher
2. Secure Connection: The connection is established using the client SSL certificate (your .pem file) and its password, as required by the ministry’s protocol.
3. “checkVoucher” Operation: The SOAP service checkVoucher is invoked, passing the code and the amount. The ministry responds by confirming:
   • The validity of the code.
   • If the requested amount is available on the voucher.
   • The personal data of the voucher holder.

5. Response to the Widget and Discount Application

The ministry’s response is processed by the app and sent back to the widget in the checkout.

• If the response is positive, the widget automatically applies a discount to the order equal to the validated amount. The order total updates in real-time.
• If the response is negative (invalid code, insufficient funds, etc.), the widget displays a specific error message received from the ministerial APIs to the customer, without applying any discount.

6. Final Order Confirmation (Confirm)

When the customer completes the purchase and confirms the order, the final and most critical phase is activated.

1. The backend receives a new request with action "confirm", containing the same code and amount.
2. A second SOAP call is made to the ministry, this time invoking the confirmVoucher operation.
3. This operation definitively debits the amount from the teacher’s voucher. It is the electronic equivalent of collecting payment.
4. The order is marked as completed in your Shopify store, with the discount applied and the voucher consumed.

Key Note: The check and confirm phases are distinct and mandatory. The “check” only verifies availability, while the “confirm” consumes the funds. An order cannot be considered valid and paid with Carta del Docente unless the confirmation call has been successful.

Technical Flow Summary

1. Customer enters code in checkout widget → HTTP POST request to /api/validate-voucher with action="check".
2. Backend verifies configuration and subscription status.
3. Backend creates SOAP client, connecting with the appropriate certificate.
4. SOAP checkVoucher call to the ministerial endpoint.
5. Positive response → discount applied in checkout.
6. Customer confirms order → New POST request to /api/validate-voucher with action="confirm".
7. SOAP confirmVoucher call that debits the amount from the voucher.
8. Order completed in Shopify.

The entire process is automated and takes place in a few seconds, ensuring a smooth checkout experience for the teacher and transaction security for the merchant, certified by the official APIs.