Configuring the App: Certificate and Mode

Configuring the App: Certificate and Mode

To enable voucher validation, you must configure a digital certificate and choose the operating mode. The app uses a .pem certificate to securely communicate with the Carte Cultura (formerly 18app) ministerial platform.

Generating the Certificate Request (.der file)

First, you need to generate a certificate request file (.der) to upload to the Carte Cultura portal.

1. Navigate to the app’s settings page in your Shopify admin.
2. Fill in the required fields for the certificate’s Distinguished Name:
   • Country (C): Typically “IT” for Italy.
   • State/Province (ST)
   • Locality (L)
   • Organization (O)
   • Organizational Unit (OU)
   • Common Name (CN)
   • Email Address
3. Enter a password to protect the private key. This password is mandatory and will be needed later.
4. Click the button to generate the request. The app will create a certificate-request-[timestamp].der file.
5. Download this .der file.

Note: The app saves the password you entered in your Shopify store’s metafields (encoded in base64) for the next step.

Uploading and Validating the Final Certificate (.cer file)

After uploading the .der file to the Carte Cultura portal, you will receive a signed certificate file with a .cer extension. You must upload this file back into the app.

1. On the app’s settings page, locate the section for uploading the final certificate.
2. Select the .cer file you received from the Carte Cultura portal.

   Note: The file must have the .cer extension. The app will not accept other formats.

3. Click to upload and validate the file. The app performs the following actions automatically:
   • It converts the .cer file to .pem format.
   • It searches among the previously generated private keys for one that matches the uploaded certificate.
   • It retrieves the password you set earlier from your shop’s metafields.
   • It combines the certificate and the matching private key to generate a final .pem certificate.

Important: If you see an error stating “No matching private key found,” ensure you are uploading the .cer file corresponding to a .der request generated by this specific app installation. You cannot use a certificate request from a different source.

Testing the Certificate Connection

Once the final .pem certificate is generated, you should test that it works correctly with the ministerial platform.

1. In the app settings, find the option to test the certificate connection.
2. Click the test button. The app will:
   • Read the certificate and password from your shop’s metafields.
   • Attempt to establish a secure SOAP connection to the Carte Cultura endpoint.
   • Return the result of the test.
3. If the test is successful, the certificate is correctly configured. If it fails, check the error message and verify your certificate files and password.

Note: A successful connection test updates a certificateValid status in your shop’s settings.

Choosing the Operating Mode: Sandbox or Production

The app can operate in two modes, which determine which ministerial platform it connects to.

• Sandbox Mode: For testing purposes. When enabled, the app uses a demo certificate and connects to the Carte Cultura test environment. Voucher validation in this mode uses mock responses for testing the checkout flow without making real API calls.
• Production Mode: For live stores. This mode uses the .pem certificate you uploaded and validated to connect to the official, live Carte Cultura platform. All voucher validations are real.

The active mode controls the visibility of the voucher widget on your checkout page. The widget is visible if either Sandbox Mode is active or a valid Production certificate is loaded.

Deleting a Certificate

If you need to remove a configured certificate:

1. Go to the certificate section in the app settings.
2. Use the option to delete the certificate. This action removes the certificate data from your Shopify metafields.
3. After deletion, the voucher widget will remain visible only if Sandbox Mode is still active. Otherwise, it will be hidden.