On This Page

Creating and Using Security Keys User Guide

This section describes how to use this user guide and where to find further information.
Audience and Purpose
This guide is written for application developers who want to use
Cybersource
 services that require a security key, including API requests.
Related Documentation
Refer to the Technical Documentation Portal for more technical documentation:
Visit the
Cybersource
 documentation hub to find additional technical documentation.
Customer Support
For support information about any service, visit the Support Center:

Recent Revisions to This Document

25.08.01

Added support for submitting a certificate signing request (CSR) as a REST API key. See Submit a Certificate Signing Request.

25.04.01

Added information about
Cybersource
 no longer supporting the SOAP toolkit key type. See the important note in Introduction to Creating and Using Security Keys and SOAP Toolkit Keys.

25.03.01

Updated the available filters for searching for keys. See Search for Keys Using Filters.
Updated how to create a meta key for portfolio users and merchant account users. See Create a Meta Key as a Portfolio User and Create a Meta Key as a Merchant Account User.
Added information about removing a meta key from all merchants and select merchants. See Remove a Meta Key from all Merchants and Remove a Meta Key from Select Merchants.

24.08.01

This revision contains only editorial changes and no technical updates.

24.06.01

This revision contains only editorial changes and no technical updates.

VISA Platform Connect: Specifications and Conditions for Resellers/Partners

The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through
Cybersource for
Visa Platform Connect
 (“VPC”) processing
. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner’s contract with Visa/Cybersource.
  1. Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.
  2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.
  3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.
  4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE
Visa Platform Connect
 ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT
Visa Platform Connect
 ACQUIRER.

Introduction to Creating and Using Security Keys

Cybersource
 requires you to use security keys when sending and receiving API messages. This guide explains how to create and manage your security keys using the
Business Center
.
A security key, also known as a
cryptographic key
, is a string of randomly or mathematically generated characters that are tied to a specific cryptographic algorithm. These keys are used to:
  • Encrypt plain text to allow users to send text across the internet with confidence that the content is secure.
  • Decrypt the encrypted message so that the text can be read by the intended recipient.
  • Validate that the encrypted message has not been tampered with while in transit.
These are the available
Cybersource
 security keys:
  • Message-Level Encryption (MLE) Keys
  • Meta Keys
  • PGP Keys
  • REST API Keys
  • Secure Acceptance Keys
  • Simple Order Keys
  • SOAP Toolkit Keys
WARNING
Cybersource
 will no longer support SOAP toolkit keys by these dates:
  • Test environment:
     July 16, 2025
  • Production environment:
     August 13, 2025
If you are integrating to the Simple Order API, you can use the compliant certificate-based
Simple Order key
. For more information, see Simple Order API Keys.
If your payment system currently uses the SOAP toolkit key, you can transition your payment system to use the certificate-based Simple Order API key. For more information about how to transition your payment system to use the compliant Simple Order API keys for authentication, see the
P12 Authentication for SOAP Toolkit Key Users Migration Guide
. Your API requests to
Cybersource
 will be rejected if you do not implement P12 authentication by the above dates.

Additional Information

For more information about cryptographic keys, see the article on Wikipedia.

Create a Security Key

This section describes how to create your security keys using the
Business Center
.
In the
Business Center
, you can use the Dashboard or Key Management to create your keys. These keys can be downloaded for you to securely store in your system.

Business Center
 Dashboard

When you log in to
the
Business Center
, the dashboard appears. You can use the Security Keys dashboard to:
  • View any keys that will expire soon.
  • Go directly to the Key Management page by clicking
    View All Keys
    .
  • Create a new key by clicking
    Generate new key
    .

Figure:

Business Center
 Dashboard

Key Management

When you log in to
the
Business Center
, navigate to
Payment Configuration > Key Management
 to access the Key Management page.
You can use the Key Management page to:
  • Search for an existing key.
  • Delete an existing key.
  • Create a new key by clicking
    Generate new key
    .
  • View any keys that will expire soon.

Message-Level Encryption Keys

Message-Level Encryption keys are required to send MLE encryption to message between the merchant and the
Cybersource
. To create an MLE key, go to the
Business Center
.
Key information:
  • Message-level encryption keys expire after 3 years.
  • Security keys can be used to make any request, including payments. Treat your security keys as you would any secure password.
  • You must use separate keys for the test and production environments.

Creating a Message-Level Encryption Key

Follow these steps to create a message-level encryption key:
  1. Log in to the
    Business Center
    :
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. Click
    + Generate Key
    .
    The Create Key page appears.
  4. Select
    Message-Level Encryption
     and click
    Generate Key
    .
  5. Enter the public key value into the text field, and click
    Create Key
    .

PGP Keys

Cybersource
 uses Pretty Good Privacy (PGP) encryption for Account Updater response files and Notice of Change (NOC) reports.
For information about Account Updater, see the
Account Updater User Guide
. For information about NOC reports, see
Electronic Check Services Developer Guide
.
A PGP public/private key pair enables you to use encryption to protect payment data. You exchange the public part of this key pair with
Cybersource
, which uses the public key to encrypt response files or NOC reports. You use the private part of the key pair to decrypt the response files or NOC reports. Only the private key can decrypt files that are encrypted with the public key.
Key information:
  • PGP keys expire after 3 years.
  • Security keys can be used to make any request, including payments. Treat your security keys as you would any secure password.
  • You must use separate keys for the test and production environments.

Creating PGP Keys

You can use any OpenPGP-compliant software to generate Pretty Good Privacy (PGP) keys. The key that you generate must be an RSA key. These free OpenPGP solutions are available:
Cybersource
 recommends that you follow these guidelines:
  • Make the key at least 2048 bits long.
  • Store the private key in an encrypted format to protect it from unauthorized use.
  • Back up the private key in case of disaster.
Place the backup of the private key on removable media, and lock it in secure storage.
Cybersource
 does not receive a copy of your private key and cannot decrypt files that are encrypted with your public key. After you create a public/private key pair, add the public key to the
Business Center
 as described in the next section.

Adding a PGP Key to Your Account

Follow these steps to add a PGP key to your account:
  1. Log in to the
    Business Center
    :
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. Click
    + Generate Key
    .
    The Create Key page appears.
  4. Select
    PGP
     and click
    Generate key
    .
  5. Enter the ASCII string into the text field, and click
    Create key
    .

Granting User Permissions

A user account requires certain permissions in order to work with PGP keys and the Account Updater request files and reports. Follow these steps to grant user permissions:
  1. Log in to the
    Business Center
    .
  2. On the left navigation panel, navigate to
    Account Management > Roles
    .
  3. Choose the role that needs to work with PGP keys and click the edit button.
    The Edit User Role page appears.
  4. Choose from these permissions:
    1. Under Credit Card Account Updater Permissions, choose
      View Status
      .
      This option enables the user to view the status of uploaded Account Updater request files and NOC reports.
    2. Under Merchant Settings Permissions, choose
      PGP Security Settings
      .
      This option gives the user permission to upload, activate, and deactivate encryption keys.
    3. Under Reporting Permissions, choose
      Report Download
      .
      This option gives the user permission to download Account Updater response files and NOC reports.
  5. Click
    Save
     when done.

REST API Keys

REST API keys are used to enable secure communication between you and
Cybersource
 when using the REST API.
The REST API supports these two types of security keys:
  • Certificates
     for using JSON Web Token authentication.
  • Shared secret key pair
     for using HTTP signature authentication.
You can create these keys using the
Business Center
 or submit your own public PEM-formatted certificate to use as your security key.
IMPORTANT
REST API keys expire after 3 years.
Security keys can be used to make any request, including payments. Treat your security keys as you would any secure password.
You must use separate keys for the test and production environments.
When you sign up for a Sandbox account, your confirmation email contains a shared secret key pair.

Create a P12 Certificate

Follow these steps to create a
.p12
 file if you are using JSON Web Tokens to secure communication.
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. Click
    + Generate
     key.
  4. Under REST APIs, choose
    REST – Certificate
    , and then click
    Generate key
    .
    If you are using a portfolio account, the Key options window appears, giving you the choice to create a meta key. For more information about how to create a meta key, see Meta Key Creation and Management.
  5. Click
    Download key
     .
  6. Create a password for the certificate by entering the password into the
    New Password
     and
    Confirm Password
     fields, and then click
    Generate key
    .
    The
    .p12
     file downloads to your desktop.
    If prompted by your system, approve the location for where the key downloads.
You can create or upload another key by clicking
Generate another key
. To view all of your created keys, use the Key Management page.
IMPORTANT
Securely store the
.p12
 file and password in your system. These credentials are required to implement certain products and you must be able to access them.

Submit a Certificate Signing Request

Follow these steps to submit your own public PEM-formatted certificate signing request (CSR) if you are using JSON Web Tokens to secure communication. You also have the option to create a P12 certificate from your CSR to use for testing purposes.
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. Click
    + Generate
     key.
  4. Under REST APIs, choose
    REST – Certificate
    , and then click
    Generate key
    .
    If you are using a portfolio account, the Key options window appears, giving you the choice to create a meta key. For more information about how to create a meta key, see Meta Key Creation and Management.
  5. Enter your public PEM-formatted certificate in the text box, then click
    Download key
     .
    If you need to generate your own CSR and private key, run this command. In this example,
    merchant
     is your organization or merchant ID (MID). You can extract the certificate value by opening the
    example.csr
     file using a text editor application.
    openssl req -new -newkey rsa:2048 -keyout private_key.pem -out example.csr -sha256 -nodes -subj "/CN=
    merchant
    "
  6. (Optional) To convert your submitted CSR into a
    .p12
     file, run this command. In this example,
    merchant
     is your organization or merchant ID (MID).
    You can use the P12 certificate for testing using the
    REST API Reference
     on the Developer Center.
    openssl pkcs12 -export -name "$(printf 'serialnumber=%s,cn=%s' "$(openssl x509 -in 
    merchant
    _certChain.pem -noout -serial | cut -d= -f2 | xxd -r -p)" "$(openssl x509 -in 
    merchant
    _certChain.pem -noout -subject | sed -n 's/.*CN=\([^/]*\).*/\1/p')" )" -out 
    merchant
    .p12 -inkey private_key.pem -in 
    merchant
    _certChain.pem
  7. When prompted, set a password for the
    .p12
     file.
You can create or upload another key by clicking
Generate another key
. To view all of your created keys, use the Key Management page.
IMPORTANT
Securely store your key's password in your system. These credentials are required to implement certain products and you must be able to access them.

Create a Shared Secret Key Pair

Follow these steps to create a shared secret key pair.
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. Click
    + Generate
     key.
  4. Under REST APIs, choose
    REST – Shared Secret
     and then click
    Generate key
    .
    The REST API Shared Secret Key page appears.
  5. Click
    Download key
     .
    The .pem file is downloaded to your desktop.
You can create or upload another key by clicking
Generate another key
. To view all of your created keys, use the Key Management page.
IMPORTANT
Securely store the
.p12
 file and password in your system. These credentials are required to implement certain products and you must be able to access them.

Secure Acceptance Key

Secure Acceptance API keys are used to enable secure communication between you, the merchant, and
Cybersource
 when using the Secure Acceptance features and APIs.
Key information:
  • Secure Acceptance keys expire after 2 years.
  • Security keys can be used to make any request, including payments. Treat your security keys as you would any secure password.
  • You must use separate keys for the test and production environments.

Creating a Secure Acceptance Key

Follow these steps to create a Secure Acceptance key:
  1. Log in to the
    Business Center
    :
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. Click
    + Generate Key
    .
    The Create Key page appears.
  4. Select
    Secure Acceptance
     and click
    Generate Key
    .
    The Key Generation page appears.
  5. Enter the required information in these fields:
    • Key Name: enter a name for this key.
    • Signature Version: select
      1
       from the drop-down menu.
    • Signature Method: select
      HMAC-SHA256
       from the drop-down menu.
    • Security Profile: select a security profile from the drop-down menu.
  6. Click
    Generate Key
     when done.
    The Key Generation page appears.
  7. To obtain the access key and secret key, either:
    • Copy the keys to your clipboard by clicking the copy button.
    • Download a text file containing both keys by clicking
      Download key
       .

Simple Order API Keys

Simple Order API keys are used to enable secure communication between the merchant and your
Cybersource
 when using Simple Order APIs.
Key information:
  • Simple Order API keys expire after 3 years.
  • Security keys can be used to make any request, including payments. Treat your security keys as you would any secure password.
  • You must use separate keys for the test and production environments.

Creating a Simple Order API Key

Follow these steps to create a Simple Order API key:
  1. Log in to the
    Business Center
    :
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. Click
    + Generate Key
    .
    The Create Key page appears.
  4. Select
    Simple Order API
     and click
    Generate Key
    .
  5. Click
    Download key
     to download the .p12 file.
    The
    Set Password
     page appears.
  6. Enter your new password and confirm it.
  7. Click
    Generate Key
     when done.
  8. The .p12 file that contains your Simple Order API key downloads to your desktop.
    IMPORTANT
    Store your .p12 file in a secure location with restricted access.

SOAP Toolkit Keys

WARNING
Cybersource
 will no longer support SOAP toolkit keys by these dates:
  • Test environment:
     July 16, 2025
  • Production environment:
     August 13, 2025
If you are integrating to the Simple Order API, you can use the compliant certificate-based
Simple Order key
. For more information, see Simple Order API Keys.
If your payment system currently uses the SOAP toolkit key, you can transition your payment system to use the certificate-based Simple Order API key. For more information about how to transition your payment system to use the compliant Simple Order API keys for authentication, see the
P12 Authentication for SOAP Toolkit Key Users Migration Guide
. Your API requests to
Cybersource
 will be rejected if you do not implement P12 authentication by the above dates.
SOAP toolkit keys are used to enable secure communication between the merchant and
Cybersource
 when using the SOAP toolkit.
Key information:
  • SOAP Toolkit keys expire after 3 years.
  • Security keys can be used to make any request, including payments. Treat your security keys as you would any secure password.
  • You must use separate keys for the test and production environments.

Creating a SOAP Toolkit Key

Follow these steps to create a SOAP Toolkit key:
  1. Log in to the
    Business Center
    :
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. Click
    + Generate Key
    .
    The Create Key page appears.
  4. Select
    SOAP Toolkit
     and click
    Generate Key
    .
    The Key Generation page appears.
  5. To obtain the SOAP Toolkit Key, either:
    • Copy the generated key to your clipboard by clicking the clipboard button.
    • Download the generated key to your desktop by clicking
      Download key
       .

Manage a Security Key

This section describes how to manage your security keys using the
Business Center
, such as searching for keys and deleting keys.
In the
Business Center
, you can use the
Business Center
 dashboard or key management to manage your keys.

Business Center
 Dashboard

When you log in to
the
Business Center
, the dashboard appears. You can use the Security Keys dashboard to:
  • View any keys that will expire soon.
  • Go directly to the Key Management page by clicking
    View All Keys
    .
  • Create a new key by clicking
    Generate new key
    .

Figure:

Business Center
 Dashboard

Key Management

When you log in to
the
Business Center
, navigate to
Payment Configuration > Key Management
 to access the Key Management page.
You can use the Key Management page to:
  • Search for an existing key.
  • Delete an existing key.
  • Create a new key by clicking
    Generate new key
    .
  • View any keys that will expire soon.

Deactivate a Key

You can deactivate these key types when you no longer need to use them:
  • PGP keys
  • Message-level encryption (MLE) keys
  • Secure Acceptance
     keys
Keys automatically deactivate when they reach the expiration date.
Follow these steps to deactivate security keys:
  1. On the left navigation panel, navigate to
    Payment Configuration
     > Key Management
    .
    The Key Management page appears.
  2. Find the key in the table of keys, or search for one using the search filters. Then click the link for that key in the Keys column.
    The Key Information page appears.
  3. Click the
    Deactivate
     button.
  4. Click
    Yes
    .

Delete a Key

You can delete a key when you no longer need to use it for payment processing.
Keys become inactive when they reach the expiration date.
Follow these steps to delete a security key:
  1. On the left navigation panel, navigate to
    Payment Configuration
     > Key Management
    .
    The Key Management page appears.
  2. In the table of keys, find the key that you want to delete and click the delete row button in the row for that key.
    The Delete Confirmation window displays.
  3. Click
    Delete
    .
    The key is deleted.

Meta Key Creation and Management

A meta key is a specialized API key that a portfolio or merchant account user can create for the purposes of processing transactions on behalf of multiple of their transacting MID accounts. Meta keys are useful for organizations whose transacting MID users do not manage or store their own individual API keys. Instead of having to create and assign a unique API key for each of your transacting MIDs, you can create and assign a single meta key to dozens or hundreds of your transacting MIDs simultaneously.
IMPORTANT
Transacting MIDs cannot generate meta keys. For security reasons, do not give a meta key to your transacting MID users.
Meta keys are available for these APIs:
  • REST
  • Simple Order API
  • SOAP
  • SCMP
When you are logged in to a portfolio account or merchant account in the
Business Center
, you can assign a meta key to a static subset of transacting MIDs or to all current and future transacting MIDs. If you choose to assign a meta key to only a subset of transacting MIDs, you can reassign the key later to all current and future transacting MIDs.
When using a meta key, the portfolio account or merchant account user submits a transaction on behalf of the transacting MID. These processed transactions are recognized as belonging to the transacting MID. Searching for or reporting on the transactions are performed at the transacting MID level. All three account types can process follow-on transactions to the initial transaction, such as a capture or refund.
Access to creating and managing meta keys is automatically enabled for all organizations. You can disable the meta key feature to not allow portfolio or merchant account users to generate meta keys or process transactions using meta keys.
WARNING
When a meta key expires, it expires for all transacting MIDs to which it is assigned. All transactions using that meta key will fail. Careful monitoring is necessary to track meta key expiration dates. You must create and assign a new key before the previous key expires. The length of time after which a key expires depends on the API for which the key was created. Read the instructions for the API key you will use.

Hierarchy of Meta Keys

In this diagram, if the portfolio user assigns a meta key to all of the transacting MIDs, every transacting MID in the diagram is assigned the key. If one of the merchant accounts assigns a meta key to all of the transacting MIDs, only the transacting MIDs belonging to that merchant account are assigned the key. The portfolio or merchant account user can also choose specific transacting MIDs to assign the meta key to.

Figure:

Portfolio Hierarchy Example

Create a Meta Key as a Portfolio User

This section describes how to create a meta key as a portfolio user in the
Business Center
.
IMPORTANT
If you would like to create meta keys using the API, contact your support team for more information.
Follow these steps to create a meta key:
  1. Log in to the
    Business Center
    :
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
  3. In the
    Merchant ID
     field, choose your portfolio ID if it is not already chosen by default.
  4. Click
    + Generate Key
    .
    The Create Key page appears.
  5. Choose a key type and click
    Generate Key
    .
    The Key options window appears if the chosen key is eligible to become a meta key.
  6. Check the
    Create as a Meta-Key
     box and click
    Continue
    .
  7. Choose one of these options to assign the key:
    • To assign this key to all accounts in the current portfolio, choose
      All current and future Merchant IDs
      , click
      Create key
      , and continue to the Create Key page. All future merchant IDs will be automatically assigned this key. You are done and do not need to proceed with the following steps.
    • To assign this key to a specific merchant or group of merchants, choose
      Custom Merchant ID selection
       and then click
      Create key
      . This key is not automatically assigned to any future merchants. Proceed to the following steps.
  8. Click
    + Add custom merchant ids
    . The Add Custom Merchant IDs page appears.
    By default, all merchant IDs are shown in the Merchant IDs table. To limit the list to a subset of merchant IDs, click
    + Add filter
    , select a search filter from the drop-down menu, and click
    Search
    .
  9. Use the check boxes to choose one or more transacting MID accounts, and click
    Submit
    .
    The Key Generation page opens.
  10. Click
    Create key
    .
    Continue to the Create Key page to view your new key.
    You can generate a new key by clicking
    + Generate Key
     again.

Create a Meta Key as a Merchant Account User

This section describes how to create a meta key as a merchant account user in the
Business Center
.
IMPORTANT
If you would like to create meta keys using the API, contact your support team for more information.
Follow these steps to create a meta key:
  1. Log in to the
    Business Center
    :
  2. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
    If you are using a portfolio user account, you can switch to a merchant account by clicking
    Switch merchant
    .
    The Quick Merchant Switch window appears.
    Choose the merchant account ID you want to switch to. Click
    Switch
     when done.
  3. In the
    Merchant ID
     search filter, choose your merchant ID.
    If you logged in from a portfolio user account or the account (
    _acct
    ) level, verify that the merchant ID you choose does not contain
    _acct
     in the ID name.
  4. Click
    + Generate Key
    .
    The Create Key page appears.
  5. Choose a key type and click
    Generate Key
    .
    The Key options window appears if the chosen key is eligible to become a meta key.
  6. Check the
    Create as a Meta-Key
     box and click
    Continue
    .
  7. Choose one of these options to assign the key:
    • To assign this key to all accounts in the current portfolio, choose
      All current and future Merchant IDs
      , click
      Create key
      , and continue to the Create Key page. All future merchant IDs will be automatically assigned this key. You are done and do not need to proceed with the following steps.
    • To assign this key to a specific merchant or group of merchants, choose
      Custom Merchant ID selection
       and then click
      Create key
      . This key is not automatically assigned to any future merchants. Proceed to the following steps.
  8. Click
    + Add custom merchant ids
    . The Add Custom Merchant IDs page appears.
    By default, all merchant IDs are shown in the Merchant IDs table. To limit the list to a subset of merchant IDs, click
    + Add filter
    , select a search filter from the drop-down menu, and click
    Search
    .
  9. Use the check boxes to choose one or more transacting MID accounts, and click
    Submit
    .
    The Key Generation page opens.
  10. Click
    Create key
    .
    Continue to the Create Key page to view your new key.
    You can generate a new key by clicking
    + Generate Key
     again.

Assign a Meta Key to All Merchants

Follow these steps to assign an existing meta key to all current MIDs and automatically assign it to all future MIDs.
  1. On the left navigation panel of the
    Business Center
    , choose
    Payment Configuration > Key Management
    .
  2. Find the key that you want to assign or revoke by searching and filtering.
  3. In the Edit Key column, click the edit button.
    The Edit Key page appears.
  4. Check the
    Meta Key
     check box if it is not already.
  5. Select
    All current and future MIDs
     if it is not already.
  6. Click
    Submit
     when done.

Assign a Meta Key to Select Merchants

Follow these steps to assign an existing meta key to a custom selection of MIDs.
  1. On the left navigation panel of the
    Business Center
    , choose
    Payment Configuration > Key Management
    .
  2. Find the key that you want to assign by searching and filtering.
  3. In the Edit Key column, click the edit button.
    The Edit Key page appears.
  4. Check the
    Meta Key
     check box if it is not already.
  5. Select
    Custom MID selection
     if it is not already.
  6. Click
    + Add custom merchant ids
    .
  7. Select the MIDs that you want to assign the meta key to.
    To filter MIDs, click
    + Add filter
    , select a filter, and click
    Search
    . Click
    Save
    .
  8. Click
    Submit
     when done.
    The Key Generation page appears.
  9. Click
    Create key
     to complete assigning the key.

Remove a Meta Key from all Merchants

Follow these steps to remove a meta key from all of the transacting MIDs that it is assigned to. This action also changes the meta key into a regular API key.
IMPORTANT
Removing a meta key does not delete the key. To delete a meta key, see Delete a Meta Key.
  1. On the left navigation panel of the
    Business Center
    , choose
    Payment Configuration > Key Management
    .
  2. Find the key that you want to assign or revoke by searching and filtering.
  3. In the Edit Key column, click the edit button.
    The Edit Key page appears.
  4. Uncheck the
    Meta Key
     checkbox.
  5. Click
    Submit
     when done.

Remove a Meta Key from Select Merchants

Follow these steps to remove a meta key from specific transacting MIDs that it is assigned to.
IMPORTANT
Removing a meta key does not delete the key. To delete a meta key, see Delete a Meta Key.
  1. On the left navigation panel of the
    Business Center
    , choose
    Payment Configuration > Key Management
    .
  2. Find the key that you want to remove by searching and filtering.
  3. In the Edit Key column, click the edit button.
    The Edit Key page appears.
  4. Verify that the
    Meta Key
     check box is checked.
  5. Verify that
    Custom MID selection
     is selected.
  6. Click
    + Add custom merchant ids
    .
  7. Select the MIDs that you want to remove the meta key from.
    To filter MIDs, click
    + Add filter
    , select a filter, and click
    Search
    . Click
    Save
    .
  8. Click
    Submit
     when done.
    The Key Generation page appears.

Convert a Meta Key or Non-Meta Key

Follow these steps to add or remove the meta key functionality to an existing API key.
If you remove meta key functionality from an API key, all MIDs assigned to that key will no longer be able to process transactions using that meta key.
  1. On the left navigation panel of the
    Business Center
    , choose
    Payment Configuration > Key Management
    .
  2. Find the key that you want to assign or revoke by searching and filtering.
  3. In the Edit Key column, click the edit button.
    The Edit Key page appears.
  4. Choose one of these options:
    • To
      add
       meta key functionality to the API key, check the
      Meta Key
       check box.
    • To
      remove
       meta key functionality from the API key, uncheck the
      Meta Key
       check box.
  5. Click
    Submit
     when done.

Delete a Meta Key

You can delete a key when you no longer need to use it for payment processing.
Keys become inactive when they reach the expiration date.
Follow these steps to delete a security key:
  1. On the left navigation panel, navigate to
    Payment Configuration
     > Key Management
    .
    The Key Management page appears.
  2. In the table of keys, find the key that you want to delete and click the delete row button in the row for that key.
    The Delete Confirmation window displays.
  3. Click
    Delete
    .
    The key is deleted.

Regenerate a Meta Key

When any security key expires, it must be updated. If you update the meta key manually, you must reassign merchants to it, which can be time-consuming. Meta key regeneration enables you to update the meta key with all of its assignments intact, streamlining the process.
  1. On the left navigation panel, choose
    Payment Configuration > Key Management
    .
    The Key Management page appears.
  2. Use the Search Filters to find the key you want to regenerate.
    Results appear in the Search Results table.
  3. Click the
    Regenerate meta key
     button for the key you want to regenerate.
    The Key Generation page opens. The new key appears on the screen. The original key remains active until its original expiration date.
  4. Provide the new key details to the merchants associated with the affected MIDs, and instruct them to update the information wherever it is used.

Meta Keys in API Requests

This section describes how to include meta keys in API requests.

REST API Payment Request with a Meta Key

REST API meta keys can use either HTTP signature or JSON Web Token methods of authentication.
If you use the SDK, see the sample code for how to configure your meta key in GitHub:
If you do not use the SDK, see the following information.

HTTP Signature

When creating the signature, use the portfolio or account ID as the value for the
v-c_merchant-id
 header. However, when sending the API request, use the transacting merchant ID (MID) as the value for the
v-c-merchant-id
 header.
Signature Headers
v-c-merchant-id : merchantId
Key id : 266438gb-2120-4q36-8da7-fbb9a196d452
Shared Key : mgWWJVV2aGQyEPwufdhhe/GiFUhsNIwYvWMih4FMCN9E=
Request Target : post /pts/v2/payments
Host : api.cybersource.com

JSON Web Token

The portfolio or account ID is not required in the header or the body. Pass the P12 certificate along with the
v-c-merchant-id
 header, using the transacting merchant account ID (MID) as the value.
JSON Web Token 
// JWT Header
{
"v-c-merchant-id":"MerchantID",
"alg":"RS256",
"x5c":["MIIB2jCCAUOgAwlBAgIWNDg...=="]
}
// JWT Claimset
{
"digest":"0qjow45/L/m6DIHd8K90rL+tBKufR1RuyE4QG7whZQ=",
"digestAlgorithm":"SHA-256",
"iat":"1594249865"
}
// JWT Signature
{
data=base64urlEncode(JWT header)+"."+base64urlEncode(Claimset) signature=RS256Hash(data,private_key);

Simple Order API Payment Request Using a Meta Key

In this Simple Order API payload, the
merchantID
 field value is the transacting merchant ID (MID) on whose behalf this transaction is being sent from the portfolio or merchant account. The portfolio or merchant account user will use a Simple Order API meta-key certificate to digitally sign the request message before sending it to
Cybersource
. There is no need to declare the portfolio ID or merchant account ID.
Simple Order API Payment Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.135">
  <merchantID>merchant12378</merchantID>
  <merchantReferenceCode>NGTS1500</merchantReferenceCode>
  <clientLibrary>Java XML</clientLibrary>
  <clientLibraryVersion>5.0.2</clientLibraryVersion>
  <clientEnvironment>Mac OS X/10.14.5/Oracle Corporation/1.8.0_161</clientEnvironment>
  <invoiceHeader>
    <merchantDescriptor>NGMerchants*MyProduct</merchantDescriptor>
    <merchantDescriptorContact>444-444-4444</merchantDescriptorContact>
  </invoiceHeader>
  <billTo>
    <firstName>TSTester</firstName>
    <lastName>NextGen</lastName>
    <street1>201 S. Division St.</street1>
    <street2>Suite 500</street2>
    <city>Ann Arbor</city>
    <state>MI</state>
    <postalCode>48104-2201</postalCode>
    <country>US</country>
    <phoneNumber>999-999-9999</phoneNumber>
    <email>[email protected]</email>
    <ipAddress>66.185.179.2</ipAddress>
  </billTo>
  <shipTo>
    <firstName>Olivia</firstName>
    <lastName>White</lastName>
    <street1>1295 Charleston Rd</street1>
    <street2>Cube 2386</street2>
    <city>Mountain View</city>
    <state>CA</state>
    <postalCode>94043</postalCode>
    <country>US</country>
    <phoneNumber>650-965-6000</phoneNumber>
  </shipTo>
  <purchaseTotals>
    <currency>usd</currency>
    <grandTotalAmount>2202</grandTotalAmount>
  </purchaseTotals>
  <card>
    <accountNumber>4111111111111111</accountNumber>
    <expirationMonth>12</expirationMonth>
    <expirationYear>2021</expirationYear>
    <cvNumber>111</cvNumber>
    <cardType>001</cardType>
  </card>
  <ccAuthService run="true">
    <commerceIndicator>internet</commerceIndicator>
    <billPayment>true</billPayment>
  </ccAuthService>
  <ccCaptureService run="true"/>
  <businessRules>
    <ignoreAVSResult>true</ignoreAVSResult>
    <ignoreCVResult>true</ignoreCVResult>
  </businessRules>
</requestMessage>

SOAP Payment Request Using a Meta Key

The request envelope requires a SOAP API password generated for the meta key. The value of the
wsse. Username
 field is the portfolio or merchant account ID. The value of the
merchantID
 field is the transacting MID on whose behalf this transaction being sent from the portfolio or account.
In this example, the request is being sent from a portfolio. The portfolio ID is
portfolioabc
 and the transacting MID is
merchant12378
.
SOAP API Payment Request
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
      <wsse:UsernameToken>
        <wsse:Username>portfolioabc</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">8SbCuVZ4FLYakM7Mm+g4jlXgV5kN/uPNfRmpTj8yKNrmvmZU25tFiTyA6Qbx4jakhKYGRDqnma/52WrOu4GQm9WbYp5xyjlE16+YQFJRXY9jQHAmikc18Na3YugZzuBbu1aRcr597pwmdxkoWb87l+6gkqJU04eHayfiMNWSkq8piBcK5fIKIah9eSQdH31DaaqAQHvJJKLL8Ki+7TYJHKc24fBLKY4QPKr0pdGNubqjJxl8YyJXozVv3F4BcmgaklqCVAiORTr/IKTczU6Y56BrPsixsoehBetzqwxnyUjRkS1172fsOFPqPwZSGhMoATyM+EYXTEZoni58q5zvvw==</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.151">
      <merchantID>merchant12378</merchantID>
      <merchantReferenceCode>BATSNTA1003</merchantReferenceCode>
      <billTo>
        <firstName>James</firstName>
        <lastName>Dough</lastName>
        <street1>600 Morgan Falls Road</street1>
        <street2>Room 2-2123</street2>
        <city>Atlanta</city>
        <state>GA</state>
        <postalCode>30350</postalCode>
        <country>US</country>
        <phoneNumber>650-965-6111</phoneNumber>
        <email>[email protected]</email>
      </billTo>
      <item id="0">
        <unitPrice>1.00</unitPrice>
      </item>
      <item id="1">
        <unitPrice>1.00</unitPrice>
      </item>
      <purchaseTotals>
        <currency>USD</currency>
      </purchaseTotals>
      <card>
        <accountNumber>4111111111111111</accountNumber>
        <expirationMonth>04</expirationMonth>
        <expirationYear>2025</expirationYear>
        <cvNumber>111</cvNumber>
        <cardType>001</cardType>
      </card>
      <ccAuthService run="true"/>
      <ccCaptureService run="true"/>
    </requestMessage>
    <urn:requestMessage xmlns:urn="urn:schemas-cybersource-com:transaction-data-1.151"/>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SCMP API Payment Request using a Meta Key

In an SCMP API payment request, the
merchant_id
 field value is the transacting MID on whose behalf this transaction being sent from the portfolio or merchant account. The value of the
sender_id
 field is the ID of the portfolio or merchant account. The portfolio or merchant account uses the SCMP API meta-key certificate to sign and encrypt the request before sending it to
Cybersource
. The SCMP API payment request below is sent from a portfolio account.
SCMP API Request
request_id=5580301042523113616883
sender_id=portfolioabc
merchant_id=merchant123
merchant_ref_number=MERCH_SCMP_123
ics_applications=ics_auth
currency=usd
return_auth_record=true
client_lib_version=Oracle Corporation/1.8.0_192/Windows Server 2008 R2/6.1/-/Java/5.2.1/Oracle Corporation/1.8.0_201/Mac OS X/10.14.3/-/Java/5.2.0
offer0=amount:2^offer_id:0^product_name:PName1^merchant_product_sku:testdl^quantity:1^product_code:clothing
ignore_avs=yes
tax_indicator=Y
user_po=LII Test
[email protected]
customer_cc_expmo=10
customer_firstname=Bob
customer_cc_expyr=2020
customer_cc_number=4111111111111111
customer_hostname=bob.bob.com
customer_ipaddress=120.1.1.1
customer_lastname=Dough
customer_phone=555-555-5555
bill_country=US
bill_city=Atlanta
bill_zip=30350
bill_address2=Room 2-2123
bill_address1=123 Test Road
bill_state=GA
[email protected]
ship_to_lastname=Jones
ship_to_country=US
ship_to_county=Monroe
ship_from_city=San Jose
ship_to_city=bloomington
ship_to_co_name=Bob's Excursion Emporium
ship_from_zip=94538
ship_from_state=CA
ship_to_zip=47404
ship_from_country=US
ship_from_county=Santa Clara
ship_to_state=indiana
ship_to_firstname=Cat
ship_to_address2=suite 2-5A
ship_to_address1=37 se main street