Manage encryption certificates

Encryption certificates are used to asymmetrically encrypt credit card data so that only the payments app can read them. This guide outlines the actions that you can take to manage encryption certificates when building a credit card payments app.

Anchor to RequirementsRequirements

• You've created a credit card payments app extension.
• You're a Partner organization owner.

Anchor to Access the encryption certificates dashboardAccess the encryption certificates dashboard

1. Log in to your Partner Dashboard as an organization owner.

2. Go to Settings, and navigate to the Partner certificates management section.

3. Click Manage Certificates to access the encryption certificates dashboard.

   

All of the features that are described in the following sections are available from this dashboard.

Anchor to Create a new encryption certificateCreate a new encryption certificate

To create a certificate in the Partner Dashboard, you need to create a Certificate Signing Request (CSR), and upload it to your dashboard. Shopify uses this CSR to generate and sign a certificate that you can use in your credit card payments app configuration.

Anchor to Step 1: Generate a Certificate Signing Request (CSR)Step 1: Generate a Certificate Signing Request (CSR)

The CSR needs to be generated with the elliptic-curve algorithm:

The CSR also accepts .crt or .cer file extensions.

The subject of the CSR, which is passed using the -subj flag, must use the following format:

Make sure to replace the <COUNTRY>, <STATE>, <CITY>, <ORGANIZATION>, and <COMMON_NAME> with correct values. This allows the Shopify team to identify you as the owner of the certificate.

Anchor to Step 2: Request an encryption certificateStep 2: Request an encryption certificate

Follow these steps to request an encryption certificate from Shopify.

1. From the certificate management dashboard, click Create Certificate, and then fill out the form.

1. In the Description field, add a short description or name to your certificate. This value will be used as a reference to your certificate so you’ll know which certificate you’re using when configuring your app.

2. In the CSR field, click Add CSR and select your CSR file, or drop your file into the upload box. The file must have the .pem,.crt or .cer extensions.

3. When the form is filled, click Save.

   A confirmation modal appears.

   

4. Click Create Encryption Certificate to confirm the request.

Anchor to Step 3: Approve your encryption certificate requestStep 3: Approve your encryption certificate request

At the email address that you use to log in to your Partner Dashboard, you'll receive an email to confirm that you requested a new certificate. Inside of the email, click Approve request.

After you approve the request, Shopify creates your certificate, and you're redirected to the main page of the encryption certificate dashboard.

Anchor to Step 4: Wait for Shopify’s approvalStep 4: Wait for Shopify’s approval

After the certificate is created, its state is set to Waiting for approval. This means that your certificate needs to be reviewed by a Shopify team member.

You won't be able to use the certificate to process payments until the review process is finished. This process can take two weeks or more, so keep this in mind for the certificate rotation process.

Learn more about certificate states.

Certificates created by Shopify are valid for one year. Read the certificate rotation process to make sure that you’re ready to update your app with a new certificate before they expire.

Anchor to Download an encryption certificateDownload an encryption certificate

After a certificate is created, you can download the certificate in a file.

From your certificate management dashboard, click on the encryption certificate that you want to download. Then, click Download.

After you click Download, an email is sent to you with a link to download the certificate. Only certificates approved by Shopify can be downloaded. The download link expires after seven days.

Anchor to Revoke an encryption certificateRevoke an encryption certificate

You might need to revoke your certificate in case of emergency. For example, you must revoke the certificate if your private key is compromised.

To revoke a certificate, go to the encryption certificate dashboard, and click on the certificate that you want to revoke. Then, click Revoke certificate.

Anchor to Rotate an encryption certificateRotate an encryption certificate

To rotate a certificate on a credit card payments app, you need to follow the steps to generate a new certificate.

After the certificate is created, wait for a Shopify team member to approve it.

Finally, when the certificate is approved, you can go to your credit card payments app extension configuration and select the new certificate, then release a new app version.

Anchor to Encryption certificate lifecycleEncryption certificate lifecycle

A certificate can be in one of multiple states during its lifecycle: