Integrations

API keys enable secure communication when sending and receiving REST API messages for automated payment processing, reporting, and other integrations.

Understanding REST API Keys

REST API security keys enable secure authentication when your systems communicate with the Visa Acceptance Solution for SMB API. There are two types of keys available:

• Shared Secret:
  • Authentication method: HTTP Signature Authentication.
  • Best for: simple integrations, quick setup.
  • Complexity: low, easy to implement.
• Certificate:
  • Authentication method: JSON Web Token (JWT) Authentication.
  • Best for: enterprise integrations, highest security.
  • Complexity: medium, requires certificate management.

REST API Key Security Best Practices

REST API keys are like passwords for your systems:

• Never share keys: never share keys with unauthorized parties.
• Store securely: use secure credential management systems.
• Separate environments: use different keys for test and production.
• Key expiration: keys expire after 3 years. Plan for renewal before expiration.
• Rotate regularly: generate new keys periodically for security.

Integrations Page Overview

The Integrations page displays a table of all your API keys with:

• Key ID: unique identifier for the key.
• Key type: REST - Shared Secret or REST - Certificate.
• Status: Active or Expired.
• Created: date the key was generated.
• Expires: expiration date (3 years from creation).
• Actions: three-dot menu for managing the key.

If you have not created any keys yet, an empty state appears with the message "No keys found" and a button to create your first key.

Certificate Key Information

Certificate keys generate a public-private key pair:

• The private key is stored in the .p12 file you download.
• The public key is stored on the Visa servers.
• Your integration uses the private key to sign requests.
• The server uses the public key to verify the signature.
• This provides strong authentication without transmitting secrets.

Using API Keys in Your Integration

For Shared Secret keys, your integration code needs these values:

• Key ID: include in the API request header.
• Shared Secret: use to generate the HTTP signature.
• Merchant ID: your account identifier.

For Certificate keys, your integration code needs these values:

• Key ID: include in the API request header.
• .p12 file: load into your application.
• Password: to decrypt the .p12 file.
• Merchant ID: your account identifier.

See the Visa Acceptance Solution for SMB API documentation for code samples, authentication implementation guides, API endpoint references, and testing tips.

Key Expiration and Renewal

All REST API keys expire after 3 years. To prepare for expiration, follow these steps 60 days before expiration:

1. Generate a new key of the same type.
2. Test the new key in your development environment.
3. Update your integration code to use the new key.
4. Deploy the updated code to production.
5. Verify the new key is working correctly.
6. Keep the old key active as a backup.

After a successful transition:

1. Monitor for any issues for 1 to 2 weeks.
2. Once confident, delete the old expired key.
3. Update your key inventory documentation.

You can have multiple active keys at the same time. This allows you to transition gradually between old and new keys, have different keys for different integrations, and maintain a backup key in case of issues.

Key Deletion Impact

When you delete a key, these effects occur:

• Any integrations using that key immediately stop working.
• The deletion cannot be undone.
• You must generate a new key and update your integrations.
• Plan deletions carefully to avoid service disruptions.

Access Integrations

The Integrations page allows you to manage API keys used for secure communication between your systems and the platform.

To access the Integrations page:

1. Click Settings in the navigation menu.
2. Click the Integrations card in the Technical section.

View REST Keys

To view existing REST API keys:

1. From the Settings tab, click Integrations.
2. To view a specific key, click the row containing it.
3. To copy the Key ID, click the Copy button. A verification message opens.

Search REST Keys

To search for a specific REST API key:

1. From the Settings tab, click Integrations.
2. Select the Search keys text field.
3. Enter a Key ID. The entered key appears.

Filter REST Keys

To filter the displayed REST API keys:

1. From the Settings tab, click Integrations.
2. To filter REST keys by type, click the Key Type: drop-down menu. Follow one or both of these options:
   • To filter the keys by REST - Shared Secret, check the box next to this option.
   • To filter the keys by REST - Certificate, check the box next to this option.
3. To filter REST keys by status, click the Status: drop-down menu. Follow one or both of these options:
   • To filter the keys by Active status, check the box next to this option.
   • To filter the keys by Expired status, check the box next to this option.

Download Keys

To download a key:

1. From the Settings tab, click Integrations.
2. Click the row containing the key you choose to download.
3. In the Key details pane, click the Download key button. A download result prompt or confirmation message appears in your browser, showing the key downloaded as a .txt file.

Delete Keys

To delete a key:

1. From the Settings tab, click Integrations.
2. To delete a key, follow one of these two methods:
   • Click the row containing the key you choose to delete. When the Key details pane displays, click the Delete key button.
   • In the Actions column for the key, click the three-dot menu icon, and click Delete.
3. At the confirmation prompt, click Delete. A verification message appears.

Create a Shared Secret

To generate a new Shared Secret:

1. From the Settings tab, click Integrations.
2. Click the Create Key button.
3. Select the key type Shared Secret, and click Generate key.
4. To retain the Shared Secret key generated, perform one or all of these steps:
   • (Optional) When the Key created successfully page opens, you can copy the Key ID or the Shared secret by clicking the Copy button next to each.
   • (Optional) To download the generated key, click the Download button.
   • (Optional) To generate another key, click Generate another key.

Create a Certificate

To generate a new Certificate:

1. From the Settings tab, click Integrations.
2. Click the Create Key button.
3. Select the key type Certificate, and click Generate key.
4. Click the Download button.
5. When the Protect your key file with a password dialog box opens, create a password.
6. Click Download key. The .p12 file downloads to your system. If prompted by your system, approve or select the download location.
7. Click the downloaded file to initiate the key generation process.
8. When prompted to either save or open the file, select Open, and follow the prompts to create and activate a new security key.
9. (Optional) Return to the Key created successfully prompt. Select the public PEM-formatted (Privacy Enhanced Mail) certificate text field, and provide the Public PEM-formatted certificate information.