Testing the Certificate Connection
Before you can validate real Carta della Cultura vouchers, you must test the connection between your Shopify store and the Ministry’s API using your uploaded certificate. This built-in tool performs a dummy SOAP call to verify your certificate is correctly formatted and the password is valid.
Prerequisites for the Test
To run the connection test, you must have already completed the following steps:
- Obtained your .cer file from the Carta della Cultura portal and converted it to a .pem file.
- Uploaded the .pem certificate file and its password in the app’s settings.
- Selected the correct environment (Sandbox for testing, Production for live sales).
How to Run the Connection Test
- Navigate to the main dashboard of the ilGhera Carta della Cultura for Shopify app within your Shopify admin.
- Locate the section for certificate configuration.
- Click the button or link labeled to test the certificate connection. This action triggers a call to the app’s internal API.
What Happens During the Test
When you initiate the test, the app performs the following actions in sequence:
- Loads Your Settings: It retrieves your shop’s configuration, including the uploaded certificate and the selected mode (Sandbox or Production), from Shopify Metafields.
- Prepares the Certificate: In Sandbox Mode, it uses a pre-configured demo certificate file stored within the app. In Production Mode, it decodes your uploaded certificate (which is stored in Base64 format) back to its original PEM content.
- Cleans the Certificate File: The app automatically removes extraneous metadata lines that can cause connection errors, leaving only the valid PEM format with BEGIN/END lines and Base64 content.
- Creates a Secure Connection: It creates a custom HTTPS agent configured specifically with your certificate, its password, and the required TLS 1.2 protocol to communicate with the Carta della Cultura SOAP endpoint.
- Performs a Dummy SOAP Call: The app attempts to create a SOAP client using the official WSDL file and the prepared HTTPS agent. A successful client creation confirms the certificate is valid and accepted by the API endpoint.
- Saves the Test Result: The outcome of the test (certificateValid: true or false) is saved back to your shop’s Metafields.
Understanding the Test Results
After the test runs, you will receive a clear result:
- Success: A message confirms the connection was successful. Your certificate is valid and correctly configured.
- Failure: An error message will explain why the test failed. Common reasons include:
- Incorrect Certificate Password: The password you entered does not match the certificate file.
- Malformed Certificate: The uploaded file is not a valid PEM certificate.
- Network or Endpoint Error: The app cannot reach the Carta della Cultura SOAP API at the configured endpoint URL.
- Certificate Not Configured: You attempted a test in Production mode without first uploading a certificate.
Note: A successful connection test is mandatory before the app’s checkout widget can validate real customer vouchers in Production mode. You do not need a valid license (trial or active) to run this test; it only validates the certificate setup.
Important: If you are in Sandbox mode, the test uses a demo certificate. Passing the test in Sandbox only confirms your app’s connectivity to the test environment. You must switch to Production mode and test with your real merchant certificate before going live.