Skip to main content

Meta Keys

Meta keys are used by portfolio account users to process transactions on behalf of multiple transacting MID accounts. A meta key is a specialized API key that eliminates the need to create and assign a unique API key for each transacting MID. 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.

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 , 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.

You must use separate keys for the test and production environments.

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.

Portfolio Hierarchy Example

Create as a Portfolio User

Follow these steps to create a meta key as a portfolio user in the :

  1. Log in to the :

    • Test:
    • Production:
    • Test:
    • Production:
    • Test:
    • Production:
    • Test:
    • Production:

    Contact customer support for access to the .

  1. On the left navigation panel, choose Payment Configuration > Key Management.

    The Key Management page appears.

  2. In the Merchant Id field, choose your portfolio ID if it is not already chosen by default.

  3. Click + Generate key.

    The Create Key page appears.

  4. Choose a key type and click Generate Key.

    The Key options page appears.

  5. Check the Create as a Meta-Key box and click Continue.

  6. 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 these 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 these steps.

  7. 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, choose a search filter from the drop-down menu, and click Search.

  8. Check the boxes of one or more transacting MID accounts, and click Submit.

    The Key Generation page opens.

  9. Click Create key.

    Continue to the Create Key page to view your new key.

    You can also generate a new key by clicking + Generate Key again.

Create as a Merchant User

Follow these steps to create a meta key as a merchant account user in the :

  1. Log in to the :

    • Test:
    • Production:
    • Test:
    • Production:
    • Test:
    • Production:
    • Test:
    • Production:

    Contact customer support for access to the .

  1. On the left navigation panel, choose Payment Configuration > Key Management.

    The Key Management page appears.

    If you are using a portfolio account to create a meta key for one of your merchant accounts, you can switch to a merchant account by clicking Switch merchant.

    The Quick Merchant Switch page appears.

    Choose the merchant account ID that you want to switch to, and click Switch.

  2. In the Merchant ID search filter, choose your merchant account 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.

  3. Click + Generate key.

    The Create Key page appears.

  4. Choose a key type and click Generate Key.

    The Key options page appears.

  5. Check the Create as a Meta-Key box and click Continue.

  6. 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 these 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 these steps.

  7. 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, choose a search filter from the drop-down menu, and click Search.

  8. Check the boxes of one or more transacting MID accounts, and click Submit.

    The Key Generation page opens.

  9. Click Create key.

    Continue to the Create Key page to view your new key.

    You can also generate a new key by clicking + Generate Key again.

Manage Meta Keys

Assign

Use these procedures to assign an existing meta key to 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, choose Payment Configuration > Key Management.

    The Key Management page appears.

  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.

Follow these steps to assign an existing meta key to a custom selection of MIDs.

  1. On the left navigation panel, choose Payment Configuration > Key Management.

    The Key Management page appears.

  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

Use these procedures to remove an assigned meta key from 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.

  1. On the left navigation panel, choose Payment Configuration > Key Management.

    The Key Management page appears.

  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.

Follow these steps to remove a meta key from specific transacting MIDs that it is assigned to.

  1. On the left navigation panel, choose Payment Configuration > Key Management.

    The Key Management page appears.

  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

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, choose Payment Configuration > Key Management.

    The Key Management page appears.

  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

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

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.

Include Meta Keys in API Requests

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:

https://github.com/CyberSource/cybersource-rest-samples-java/blob/master/README.md#setting-your-api-credentials

If you do not use the SDK, see this authentication 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.

v-c-merchant-id : merchantIdKey id : 266438gb-2120-4q36-8da7-fbb9a196d452Shared Key : mgWWJVV2aGQyEPwufdhhe/GiFUhsNIwYvWMih4FMCN9E=Request Target : post /pts/v2/paymentsHost : 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.

// 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);

Use a Meta Key with the Simple Order API

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 . There is no need to declare the portfolio ID or merchant account ID.

<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>4xxxxxxxxxxx1111</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>

Use a Meta Key with the SOAP Toolkit

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 is 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.

<?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>4xxxxxxxxxxx1111</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>

Last published: September 29, 2026