Get Started with TMS for Partners
Accept cards, digital wallets, and alternative payment methods through one API integration.
This guide walks partners through setting up Token Management Service () for merchant onboarding. Choose the integration model that matches how you use :
Enable your merchants to manage network tokens directly through as a standalone service, independent of payment processing. handles token provisioning, cryptogram generation, and life-cycle updates.
Register for a Portfolio
Portfolio MIDs for Partners
Partners need to onboard merchants using a portfolio MID. To create a portfolio MID, contact support.
Customer support will respond with a questionnaire. Complete this information:
- Organization ID: Portfolio MID name
- Environment: Test and Production
- Business information: The business name and address
- Business contact: The contact that receives an email registration link to gain access to through the portfolio MID.
- Technical contact: The contact that receives automatically generated notifications, such as product updates, as well as non-urgent notifications.
- Emergency contact: The contact that receives urgent messages such as service outage notifications
- Merchant notifications: This will send a welcome email to the business contact associated with the end merchant.
- Processing information: Not applicable.
- Product information: only
- Customer Support: Not applicable.
- Branding: Not applicable.
For background on merchant ID (MID) types and hierarchy, see Board a Merchant with TMS.
Create API Keys
Create a Shared Secret Key
Create a REST API shared secret key to authenticate the requests you send to . You must create separate keys for the test and production environments.
Log in to the :
- Test:
- Production:
On the left navigation panel, choose Payment Configuration > Key Management.
Click + Generate key on the Key Management page.
Under REST APIs, choose REST – Shared Secret and then click Generate key.
The REST API Shared Secret Key page appears.
Click Download key.
The .pem file downloads to your desktop. The Key value is your key ID and the Shared Secret value is your shared secret key.
To create or submit another key, click Generate another key. To view all of your created keys, go to the Key Management page.
For more information, see REST API Keys.
Create a Token Management MLE Key
Message-Level Encryption Keys
You must use token management message-level encryption (MLE) keys in order for personally identifiable information, such as payment information, to be returned unmasked by . You must create an MLE security key for your merchant account in the before a response can return unmasked payment information using MLE.
MLE keys can be created at the portfolio and transacting levels of an organization. You must create an MLE key at the portfolio level of an organization if you want to use a single MLE key for the encryption and decryption of payment information for multiple merchants. To do so, you must log in to the using your portfolio credentials and ensure that the MLE key is generated for your organization.
MLE 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.
Before You Begin
You must have a tool such as OpenSSL installed on your system.
To create an MLE key, you must first extract a public key. You can use a tool such as OpenSSL to extract the key:
openssl genrsa -out private.pem 2048 && openssl rsa -in private.pem -outform PEM -pubout -out public.pemFollow these steps to create a Token Management MLE key:
Log in to the :
- Test:
- Production:
On the left navigation panel, choose Payment Configuration > Key Management.
Click + Generate key.
Select Token Management MLE and click Generate Key.
Enter the public key value into the text field, and click Create Key.
On the Key Management page, select Message Level Encryption from the Key Type drop-down list to view your keys.
Select your key.
To change the status of the key from Inactive to Active, click Change Status.
Click Confirm to change the status of the key.
Board a Merchant with TMS
A MID is a unique value within that you define during account registration. Your MID identifies your merchant account and payment configuration within systems. You provide this identifier when you sign in to the and submit transactions to .
Multiple MIDs can be configured for various token types. You receive the instrument identifier token regardless of your account's token type. Reasons for multiple MIDs include:
- You have multiple processors.
- Point-of-sale terminals have unique MIDs, which are usually configured for the PAN-only instrument identifier token.
When you have multiple MIDs, you can set up one token vault to which all of your MIDs have access or set up multiple vaults to limit access to tokens.
The is an online portal provisioned to partners and end merchants. You can use this portal to onboard merchants, view transactional activity, and generate and download reports.
There are two environments associated with the : test and production. Each has its own corresponding URL to gain access:
- Test:
- Production:
To gain access to the , partners and merchants must be provisioned with an Organization ID, otherwise known as a merchant ID (MID). There are multiple types of MIDs:
- Portfolio: This is typically a MID provisioned to partners. Portfolio MIDs enable partners to onboard merchants into either a test or production environment.
- Merchant: This is a parent MID that can house multiple transactional MIDs. This is directly associated with the end merchant and is created by the partner under the portfolio MID. This MID is attached to specific functionality such as the token vault ().
- Transactional: This is a child MID. Each partner's end merchant may have multiple transactional MIDs. The transactional MID is typically used for processing into , for example, to provision a network token via the API. This is directly associated with the partner's end merchant and is created by the partner under the portfolio MID.
Board a Merchant Using the Business Center
You can board a merchant for directly in the .
- Log in to the test environment or production environment:
- In the left navigation panel, choose Portfolio Management > Merchants > Manage Merchants, then click + Add Merchant.
- Select Board a new merchant account to create a new merchant account, or Add to an existing account to add a transacting merchant to an existing merchant organization. Click Next.
- If more than one boarding package is available, select one from the drop-down menu, or search for it, then click Next. skips this step if only one boarding package exists.
- Click Start in the Merchant Account Information section and enter the account details. (Optional) Click Skip in the Hierarchy Details section to bypass hierarchy setup.
- Click Start in the Transacting Organization and Products section. Enter the transacting organization name and organization ID, then locate Token Management Service and select Enabled from the Enablement drop-down menu.
- Click Configure, select a template from the Product Configuration Template drop-down menu, and click Apply to save the configuration.
For details, see Add TMS to a Merchant Account in the Merchant Boarding User Guide.
For information about creating the underlying merchant organization structure, see Create Organizations in the Merchant Boarding User Guide () or Merchant Boarding User Guide (Visa Acceptance Solutions).
Board a Merchant Using the API
You can also board a merchant for through the Boarding Registration Service API. Choose the scenario that matches your merchant's onboarding path.
Enable TMS Using a Template
Enable Token Management Service for a transacting organization using a Token Management Service product configuration template.
POST /boarding/v1/registrations
POST /boarding/v1/registrations
View API Sample Request
{ "registrationInformation": { "boardingFlow": "ADDPRODUCT" }, "organizationInformation": { "parentOrganizationId": "3b2bwnhbm7cdzath0qcn0luhkpvb", "type": "TRANSACTING", "configurable": false, "businessInformation": { "name": "Test Merchant", "address": { "country": "US", "address1": "123 Main", "locality": "Seattle", "administrativeArea": "WA", "postalCode": "99999" }, "businessContact": { "firstName": "Jane", "lastName": "Smith", "phoneNumber": "5551234567", "email": "[email protected]" } } }, "productInformation": { "selectedProducts": { "commerceSolutions": { "tokenManagement": { "subscriptionInformation": { "enabled": true, "selfServiceability": "NOT_SELF_SERVICEABLE" }, "configurationInformation": { "templateId": "43107BC1-E3DA-4019-9306-4510AD4DE05F" } } } } }}{ "id": "94498504004", "submitTimeUtc": "2024-07-01T16:25:20Z", "status": "SUCCESS", "registrationInformation": { "mode": "COMPLETE", "boardingPackageId": "1168704004" }, "organizationInformation": { "organizationId": "{MerchantAccountOrgId}", "parentOrganizationId": "{PortfolioOrgId}" }, "message": "Request was processed successfully"}For the full set of required fields, see Enable Token Management Service Using a Template in the Merchant Boarding Developer Guide.
Enable TMS and Enroll in Network Tokenization for a New Merchant
Enable Token Management Service and enroll a new merchant in network tokenization with Visa and Mastercard in a single request.
POST /boarding/v1/registrations
POST /boarding/v1/registrations
View API Sample Request
{ "registrationInformation": { "boardingFlow": "ENTERPRISE" }, "organizationInformation": { "organizationId": "yourmerchantorgidhere", "parentOrganizationId": "yourportfolioorgidhere", "type": "MERCHANT", "configurable": true, "businessInformation": { "name": "NetworkTokenMerchant", "address": { "country": "US", "address1": "123456 SandMarket", "locality": "ORMOND BEACH", "administrativeArea": "FL", "postalCode": "32176" }, "websiteUrl": "https://www.NetworkTokenMerchant.com", "businessContact": { "firstName": "Token", "lastName": "Man", "phoneNumber": "6574567813", "email": "[email protected]" } } }, "productInformation": { "selectedProducts": { "commerceSolutions": { "tokenManagement": { "subscriptionInformation": { "enabled": true }, "configurationInformation": { "configurations": { "vault": { "location": "GDC", "defaultTokenType": "CUSTOMER", "tokenFormats": { "customer": "32_HEX", "paymentInstrument": "32_HEX", "instrumentIdentifierCard": "19_DIGIT_LAST_4", "instrumentIdentifierBankAccount": "32_HEX" }, "sensitivePrivileges": { "cardNumberMaskingFormat": "FIRST_6_LAST_4" }, "networkTokenServices": { "notifications": { "enabled": true }, "paymentCredentials": { "enabled": true }, "synchronousProvisioning": { "enabled": false }, "visaTokenService": { "enableService": true, "enableTransactionalTokens": true }, "mastercardDigitalEnablementService": { "enableService": true, "enableTransactionalTokens": true } } }, "networkTokenEnrollment": { "businessInformation": { "name": "NetworkTokenMerchant", "doingBusinessAs": "NetworkTokenCo1", "address": { "country": "US", "locality": "ORMOND BEACH" }, "websiteUrl": "https://www.NetworkTokenMerchant.com", "acquirer": { "acquirerId": "40010052242", "acquirerMerchantId": "MerchantOrgID" } }, "networkTokenServices": { "visaTokenService": { "enrollment": true }, "mastercardDigitalEnablementService": { "enrollment": true } } } } } } } } }}{ "id": "94498504004", "submitTimeUtc": "2024-07-01T16:25:20Z", "status": "SUCCESS", "registrationInformation": { "mode": "COMPLETE", "boardingPackageId": "1168704004" }, "organizationInformation": { "organizationId": "{MerchantAccountOrgId}", "parentOrganizationId": "{PortfolioOrgId}" }, "message": "Request was processed successfully"}For the full set of required fields, see Enable TMS and Enroll in Network Tokenization for a New Merchant in the Merchant Boarding Developer Guide.
Enable TMS and Enroll in Network Tokenization for an Existing Merchant
Enable Token Management Service and enroll an existing merchant organization in network tokenization with Visa and Mastercard.
POST /boarding/v1/registrations
POST /boarding/v1/registrations
View API Sample Request
{ "registrationInformation": { "boardingFlow": "ADDPRODUCT" }, "organizationInformation": { "organizationId": "yourmerchantorgidhere", "parentOrganizationId": "yourportfolioorgidhere", "type": "MERCHANT", "configurable": true, "businessInformation": { "name": "TokenMerchant", "address": { "country": "US", "address1": "123456 SandMarket", "locality": "ORMOND BEACH", "administrativeArea": "FL", "postalCode": "32176" }, "websiteUrl": "https://www.MerchantUrlHere.com", "businessContact": { "firstName": "Token", "lastName": "Man", "phoneNumber": "6574567813", "email": "[email protected]" } } }, "productInformation": { "selectedProducts": { "commerceSolutions": { "tokenManagement": { "subscriptionInformation": { "enabled": true }, "configurationInformation": { "configurations": { "vault": { "location": "GDC", "defaultTokenType": "CUSTOMER", "tokenFormats": { "customer": "32_HEX", "paymentInstrument": "32_HEX", "instrumentIdentifierCard": "19_DIGIT_LAST_4", "instrumentIdentifierBankAccount": "32_HEX" }, "sensitivePrivileges": { "cardNumberMaskingFormat": "FIRST_6_LAST_4" } }, "networkTokenEnrollment": { "businessInformation": { "name": "TokenMerchant", "doingBusinessAs": "NetworkTokenCo1", "address": { "country": "US", "locality": "ORMOND BEACH" }, "websiteUrl": "https://www.MerchantUrlHere.com", "acquirer": { "acquirerId": "40010052242", "acquirerMerchantId": "yourmerchantorgidhere" } }, "networkTokenServices": { "visaTokenService": { "enrollment": true }, "mastercardDigitalEnablementService": { "enrollment": true } } }, "networkTokenServices": { "notifications": { "enabled": true }, "paymentCredentials": { "enabled": true }, "visaTokenService": { "enableService": true, "enableTransactionalTokens": true }, "mastercardDigitalEnablementService": { "enableService": true, "enableTransactionalTokens": true } } } } } } } }}{ "id": "94498504004", "submitTimeUtc": "2024-07-01T16:25:20Z", "status": "SUCCESS", "registrationInformation": { "mode": "COMPLETE", "boardingPackageId": "1168704004" }, "organizationInformation": { "organizationId": "{MerchantAccountOrgId}", "parentOrganizationId": "{PortfolioOrgId}" }, "message": "Request was processed successfully"}For the full set of required fields, see Enable TMS and Enroll in Network Tokenization for an Existing Merchant in the Merchant Boarding Developer Guide.
Configure Your Merchant's Token Vault
Token Vault Management
Token vaults are where merchants store their customer and payment data. A internal user can enable the vault.
Vaults are assigned to an owner, and all data within the vault belongs to the owner. You can grant permission to individual MIDs to create, retrieve, update, and delete tokens within a vault. Created tokens belong to the owner of the vault, not the creator of the token. If you remove a MID from a vault, it can no longer access any tokens within that vault, including tokens created under that MID.
Configure Vault Settings
- Log in to the test environment or production environment:
- Test:
- Production:
In the left navigation panel, click the Token Management icon.
Click Vault Management New. The Vault Management page appears. From the Vault Owner drop-down list, select the vault owner.
In the Details column, click Vault Settings. The Edit Vault page appears.
Click Edit. A dialog box appears with a message to warn you that changing your vault settings could result in your merchants being unable to access tokens, which could result in failing transactions. Click Yes if you want to continue.
Enter the vault name, supported payment methods, supported token types and formats, card number masking format, payment instrument storing configuration, and the webhook URL. For each token type, you can choose from these token formats:
- 32 Character Hex
- 22 Digits
- 19 Digits Luhn Check Passing
- 16 Digits Luhn Check Passing
- Click SAVE.
To return to the vault management page, click VAULT MANAGEMENT.
Configure Vault Access
- Log in to the test environment or production environment:
- Test:
- Production:
In the left navigation panel, click the Token Management icon.
Click Vault Management New. The Vault Management page appears.
Select the vault owner that you want to configure from the Vault Owner drop-down list.
In the Details column, click Access Settings. The MID Access page appears.
Check the box for the vault settings you want to enable for each merchant you want to configure:
- Visa Token
- Mastercard Token
- Card Unmasked
- Create
- Update
- Retrieve
- Click Submit to save your settings.
Enable Network Tokenization
Network tokenization replaces a customer's primary account number (PAN) with a network token. A network token is a tokenized card number that is issued by card networks (for example, Visa, Mastercard, American Express, and Discover). Network tokens use the same format as a PAN but are domain-restricted and cryptographically secured. This reduces exposure to fraud and data breaches.
For more information about how network tokens work and their benefits, see Network Tokens.
Network token enablement is currently a manual process and requires a request to be sent to support. For more information about network token enablement, visit the Support Center:
Configure Network Tokenization by Card Type
Token Requestor IDs
A token requestor ID (TRID) is a unique identifier that entities such as merchants use to request network tokens from token providers. Having a TRID is a prerequisite for enabling network tokenization.
Visa and Mastercard TRIDs
An internal user can enroll a merchant as a VISA or Mastercard token requestor through the .
When the enrollment is submitted, the relationship ID and token requestor ID appear on the page for Visa Token Service (VTS) and the token requestor ID appears for Mastercard.
To request a TRID from the token provider, uses merchant business details already stored. If any of the details are not present, a dialog form should appear prompting you to complete the missing information.
American Express TRIDs
Enrollment as a token requestor for American Express is a manual process. Contact your representative to request the TRID for American Express.
Allow 2 to 3 days for the completion of your request.
Each entity must register with the token provider to get a TRID. Contact a Cybersource representative to enroll a merchant as a token requestor.
- Log in to the test environment or production environment:
- Test:
- Production:
In the left navigation panel, click the Token Management icon.
Click Vault Management New. The Vault Management page appears.
Select the vault owner that you want to configure from the Vault Owner drop-down list.
In the Details column, click Network Tokenization. The Network Tokenization page appears.
Configure your network tokenization settings for each supported card type:
a. On the VISA tab, switch the Enroll to VISA Token Services button to On to enable Visa token services.
The required business information for the merchant will be populated:
- Merchant name - Website URL - Country code
b. Click Onboard with Acquirer ID and enter the required information:
- Acquirer ID: Set the value to 40010052242. This is a static acquirer ID that is used for . - Acquirer merchant ID: Enter your organization ID.
c. Click Manage Details.
d. Check Enable Visa Token Provisioning to enable Visa network token provisioning.
e. Check Enable Visa Token Transactions to enable Visa transaction processing using network tokens.
f. Enter the token requestor ID (TRID) and relationship ID if necessary.
g. Click Submit to save your settings.
a. On the MASTERCARD tab, switch the Enroll to MASTERCARD Token Services button to On to enable Mastercard token services.
b. Click Manage Details.
c. Check Enable Mastercard Token Provisioning to enable Mastercard network token provisioning.
d. Check Enable Mastercard Token Transactions to enable Mastercard transaction processing using network tokens.
e. Enter the token TRID and relationship ID if necessary.
f. Click Submit to save your settings.
a. On the AMERICAN EXPRESS tab, switch the Enroll to AMERICAN EXPRESS Token Services button to On to enable American Express token services.
b. Check Enable American Express Token Provisioning to enable American Express network token provisioning.
c. Check Enable American Express Token Transactions to enable American Express transaction processing using network tokens.
d. Enter the token TRID and SE number if necessary.
e. Click Submit to save your settings.
Tokenize Payment Information
Provision a network token for a card number using the Tokenized Cards API, then retrieve, refresh, and remove that token as needed.
For details on authenticating and constructing requests to the API, see Requesting the Token Management Service.
Provision a Network Token
Create a network token for a card number.
POST /tms/v2/tokenized-cards
POST /tms/v2/tokenized-cards
View API Sample Request
{ "source": "ONFILE", "card": { "number": "X622943123116478", "expirationMonth": "12", "expirationYear": "2026" }}{ "_links": { "self": { "href": "/tms/v2/tokenized-cards/518CA1611EF98697E063AF598E0ADFB9" }, "instrumentIdentifier": { "href": "/tms/v1/instrumentidentifiers/7031530000033441624" } }, "id": "518CA1611EF98697E063AF598E0ADFB9", "object": "tokenizedCard", "state": "ACTIVE", "paymentAccountReference": "V0010013025104530884197510742", "number": "489537XXXXXX1624", "type": "visa", "card": { "suffix": "6478", "expirationMonth": "12", "expirationYear": "2026" }, "source": "ONFILE"}For the full set of required fields, see Network Tokens.
Retrieve Network Token and Cryptogram
Generate standard payment credentials, including the network token value and cryptogram, for an existing tokenized card.
POST /tms/v2/tokens/{tokenId}/payment-credentials
POST /tms/v2/tokens/{tokenId}/payment-credentials
View API Sample Request
{}The {tokenId} is the tokenized card ID returned in the id field when you provisioned the network token. The response is a JSON Web Encryption (JWE) payload; for details on decrypting it, see Payment Credentials.
Retrieve Latest PAN Suffix and Expiration Details
Retrieve the current state of a network token, including the latest PAN suffix and expiration details.
GET /tms/v2/tokenized-cards/{tokenizedCardId}
GET /tms/v2/tokenized-cards/{tokenizedCardId}
View API Sample Request
{ "_links": { "self": { "href": "/tms/v2/tokenized-cards/223ACDECF1681954E063A2598D0A786D" }, "instrumentIdentifier": { "href": "/tms/v1/instrumentidentifiers/7040890000006625091" } }, "id": "223ACDECF1681954E063A2598D0A786D", "object": "tokenizedCard", "state": "ACTIVE", "number": "521415XXXXXX5091", "expirationMonth": "10", "expirationYear": "2027", "type": "mastercard", "card": { "suffix": "0747", "expirationMonth": "12", "expirationYear": "2031" }, "source": "ONFILE"}The {tokenizedCardId} is the tokenized card ID returned in the id field when you provisioned the network token. For details, see Network Tokens.
Delete Network Token
Remove a network token that you no longer need.
DELETE /tms/v2/tokenized-cards/{tokenizedCardId}
DELETE /tms/v2/tokenized-cards/{tokenizedCardId}
View API Sample Request
DELETE /tms/v2/tokenized-cards/223ACDECF1681954E063A2598D0A786DA successful delete returns an empty HTTP 204 No Content status. For details, see Network Tokens.
Subscribe to Network Token Updates
Create a digital signature key, then create a webhook subscription to receive notifications about network token lifecycle events, such as provisioning, updates, and device binding.
Create a Digital Signature Key
You must create a digital signature key to enable to send notifications to your servers.
POST /kms/egress/v2/keys-sym
POST /kms/egress/v2/keys-sym
{ "clientRequestAction": "CREATE", "keyInformation": { "provider": "nrtd", "tenant": "merchantName", "keyType": "sharedSecret", "organizationId": "merchantName" }}{ "submitTimeUtc": "2021-03-17T06:53:06+0000", "status": "SUCCESS", "keyInformation": { "provider": "NRTD", "tenant": "merchantName", "organizationId": "merchantName", "keyId": "bdc0fe52-091e-b0d6-e053-34b8d30a0504", "key": "u3qgvoaJ73rLJdPLTU3moxrXyNZA4eo5dklKtIXhsAE=", "keyType": "sharedSecret", "status": "Active", "expirationDate": "2022-03-17T06:53:06+0000" }}Create a Webhook Subscription
Subscribe to network token lifecycle event notifications.
POST /notification-subscriptions/v1/webhooks
POST /notification-subscriptions/v1/webhooks
View API Sample Request
{ "organizationId": "merchantOrgId", "productId": "tokenManagement", "url": "https://www.yoursite.com/webhooks/tms/notifications", "eventTypes": [ "tms.networktoken.provisioned", "tms.networktoken.updated", "tms.networktoken.binding" ]}{ "submitTimeUtc": "2023-04-12T10:15:30+0000", "status": "SUCCESS", "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationId": "merchantOrgId", "productId": "tokenManagement", "url": "https://www.yoursite.com/webhooks/tms/notifications", "eventTypes": [ "tms.networktoken.provisioned", "tms.networktoken.updated", "tms.networktoken.binding" ]}Get Details on a Webhook Subscription
Retrieve the details of an existing webhook subscription.
GET /notification-subscriptions/v1/webhooks/{webhookID}
GET /notification-subscriptions/v1/webhooks/{webhookID}
View API Sample Request
{ "submitTimeUtc": "2023-04-12T10:15:30+0000", "status": "SUCCESS", "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationId": "merchantOrgId", "productId": "tokenManagement", "url": "https://www.yoursite.com/webhooks/tms/notifications", "eventTypes": [ "tms.networktoken.provisioned", "tms.networktoken.updated", "tms.networktoken.binding" ]}For details on retrieving, updating, and deleting webhook subscriptions, see Webhooks.
Enable your merchants to create and manage tokens as part of their payment authorization flow on . This extends existing payment flows with minimal changes, while manages token life-cycle and transaction handling.
Register for a Portfolio
Portfolio MIDs for Partners
Partners need to onboard merchants using a portfolio MID. To create a portfolio MID, contact support.
Customer support will respond with a questionnaire. Complete this information:
- Organization ID: Portfolio MID name
- Environment: Test and Production
- Business information: The business name and address
- Business contact: The contact that receives an email registration link to gain access to through the portfolio MID.
- Technical contact: The contact that receives automatically generated notifications, such as product updates, as well as non-urgent notifications.
- Emergency contact: The contact that receives urgent messages such as service outage notifications
- Merchant notifications: This will send a welcome email to the business contact associated with the end merchant.
- Processing information: Not applicable.
- Product information: only
- Customer Support: Not applicable.
- Branding: Not applicable.
For background on merchant ID (MID) types and hierarchy, see Board a Merchant with TMS.
Create API Keys
Create a Shared Secret Key
Create a REST API shared secret key to authenticate the requests you send to . You must create separate keys for the test and production environments.
Log in to the :
- Test:
- Production:
On the left navigation panel, choose Payment Configuration > Key Management.
Click + Generate key on the Key Management page.
Under REST APIs, choose REST – Shared Secret and then click Generate key.
The REST API Shared Secret Key page appears.
Click Download key.
The .pem file downloads to your desktop. The Key value is your key ID and the Shared Secret value is your shared secret key.
To create or submit another key, click Generate another key. To view all of your created keys, go to the Key Management page.
For more information, see REST API Keys.
Create a Token Management MLE Key
Message-Level Encryption Keys
You must use token management message-level encryption (MLE) keys in order for personally identifiable information, such as payment information, to be returned unmasked by . You must create an MLE security key for your merchant account in the before a response can return unmasked payment information using MLE.
MLE keys can be created at the portfolio and transacting levels of an organization. You must create an MLE key at the portfolio level of an organization if you want to use a single MLE key for the encryption and decryption of payment information for multiple merchants. To do so, you must log in to the using your portfolio credentials and ensure that the MLE key is generated for your organization.
MLE 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.
Before You Begin
You must have a tool such as OpenSSL installed on your system.
To create an MLE key, you must first extract a public key. You can use a tool such as OpenSSL to extract the key:
openssl genrsa -out private.pem 2048 && openssl rsa -in private.pem -outform PEM -pubout -out public.pemFollow these steps to create a Token Management MLE key:
Log in to the :
- Test:
- Production:
On the left navigation panel, choose Payment Configuration > Key Management.
Click + Generate key.
Select Token Management MLE and click Generate Key.
Enter the public key value into the text field, and click Create Key.
On the Key Management page, select Message Level Encryption from the Key Type drop-down list to view your keys.
Select your key.
To change the status of the key from Inactive to Active, click Change Status.
Click Confirm to change the status of the key.
Board a Merchant with TMS
A MID is a unique value within that you define during account registration. Your MID identifies your merchant account and payment configuration within systems. You provide this identifier when you sign in to the and submit transactions to .
Multiple MIDs can be configured for various token types. You receive the instrument identifier token regardless of your account's token type. Reasons for multiple MIDs include:
- You have multiple processors.
- Point-of-sale terminals have unique MIDs, which are usually configured for the PAN-only instrument identifier token.
When you have multiple MIDs, you can set up one token vault to which all of your MIDs have access or set up multiple vaults to limit access to tokens.
The is an online portal provisioned to partners and end merchants. You can use this portal to onboard merchants, view transactional activity, and generate and download reports.
There are two environments associated with the : test and production. Each has its own corresponding URL to gain access:
- Test:
- Production:
To gain access to the , partners and merchants must be provisioned with an Organization ID, otherwise known as a merchant ID (MID). There are multiple types of MIDs:
- Portfolio: This is typically a MID provisioned to partners. Portfolio MIDs enable partners to onboard merchants into either a test or production environment.
- Merchant: This is a parent MID that can house multiple transactional MIDs. This is directly associated with the end merchant and is created by the partner under the portfolio MID. This MID is attached to specific functionality such as the token vault ().
- Transactional: This is a child MID. Each partner's end merchant may have multiple transactional MIDs. The transactional MID is typically used for processing into , for example, to provision a network token via the API. This is directly associated with the partner's end merchant and is created by the partner under the portfolio MID.
Board a Merchant Using the Business Center
You can board a merchant for directly in the .
- Log in to the test environment or production environment:
- In the left navigation panel, choose Portfolio Management > Merchants > Manage Merchants, then click + Add Merchant.
- Select Board a new merchant account to create a new merchant account, or Add to an existing account to add a transacting merchant to an existing merchant organization. Click Next.
- If more than one boarding package is available, select one from the drop-down menu, or search for it, then click Next. skips this step if only one boarding package exists.
- Click Start in the Merchant Account Information section and enter the account details. (Optional) Click Skip in the Hierarchy Details section to bypass hierarchy setup.
- Click Start in the Transacting Organization and Products section. Enter the transacting organization name and organization ID, then locate Token Management Service and select Enabled from the Enablement drop-down menu.
- Click Configure, select a template from the Product Configuration Template drop-down menu, and click Apply to save the configuration.
For details, see Add TMS to a Merchant Account in the Merchant Boarding User Guide.
For information about creating the underlying merchant organization structure, see Create Organizations in the Merchant Boarding User Guide () or Merchant Boarding User Guide (Visa Acceptance Solutions).
Board a Merchant Using the API
You can also board a merchant for through the Boarding Registration Service API. Choose the scenario that matches your merchant's onboarding path.
Enable TMS Using a Template
Enable Token Management Service for a transacting organization using a Token Management Service product configuration template.
POST /boarding/v1/registrations
POST /boarding/v1/registrations
View API Sample Request
{ "registrationInformation": { "boardingFlow": "ADDPRODUCT" }, "organizationInformation": { "parentOrganizationId": "3b2bwnhbm7cdzath0qcn0luhkpvb", "type": "TRANSACTING", "configurable": false, "businessInformation": { "name": "Test Merchant", "address": { "country": "US", "address1": "123 Main", "locality": "Seattle", "administrativeArea": "WA", "postalCode": "99999" }, "businessContact": { "firstName": "Jane", "lastName": "Smith", "phoneNumber": "5551234567", "email": "[email protected]" } } }, "productInformation": { "selectedProducts": { "commerceSolutions": { "tokenManagement": { "subscriptionInformation": { "enabled": true, "selfServiceability": "NOT_SELF_SERVICEABLE" }, "configurationInformation": { "templateId": "43107BC1-E3DA-4019-9306-4510AD4DE05F" } } } } }}{ "id": "94498504004", "submitTimeUtc": "2024-07-01T16:25:20Z", "status": "SUCCESS", "registrationInformation": { "mode": "COMPLETE", "boardingPackageId": "1168704004" }, "organizationInformation": { "organizationId": "{MerchantAccountOrgId}", "parentOrganizationId": "{PortfolioOrgId}" }, "message": "Request was processed successfully"}For the full set of required fields, see Enable Token Management Service Using a Template in the Merchant Boarding Developer Guide.
Enable TMS and Enroll in Network Tokenization for a New Merchant
Enable Token Management Service and enroll a new merchant in network tokenization with Visa and Mastercard in a single request.
POST /boarding/v1/registrations
POST /boarding/v1/registrations
View API Sample Request
{ "registrationInformation": { "boardingFlow": "ENTERPRISE" }, "organizationInformation": { "organizationId": "yourmerchantorgidhere", "parentOrganizationId": "yourportfolioorgidhere", "type": "MERCHANT", "configurable": true, "businessInformation": { "name": "NetworkTokenMerchant", "address": { "country": "US", "address1": "123456 SandMarket", "locality": "ORMOND BEACH", "administrativeArea": "FL", "postalCode": "32176" }, "websiteUrl": "https://www.NetworkTokenMerchant.com", "businessContact": { "firstName": "Token", "lastName": "Man", "phoneNumber": "6574567813", "email": "[email protected]" } } }, "productInformation": { "selectedProducts": { "commerceSolutions": { "tokenManagement": { "subscriptionInformation": { "enabled": true }, "configurationInformation": { "configurations": { "vault": { "location": "GDC", "defaultTokenType": "CUSTOMER", "tokenFormats": { "customer": "32_HEX", "paymentInstrument": "32_HEX", "instrumentIdentifierCard": "19_DIGIT_LAST_4", "instrumentIdentifierBankAccount": "32_HEX" }, "sensitivePrivileges": { "cardNumberMaskingFormat": "FIRST_6_LAST_4" }, "networkTokenServices": { "notifications": { "enabled": true }, "paymentCredentials": { "enabled": true }, "synchronousProvisioning": { "enabled": false }, "visaTokenService": { "enableService": true, "enableTransactionalTokens": true }, "mastercardDigitalEnablementService": { "enableService": true, "enableTransactionalTokens": true } } }, "networkTokenEnrollment": { "businessInformation": { "name": "NetworkTokenMerchant", "doingBusinessAs": "NetworkTokenCo1", "address": { "country": "US", "locality": "ORMOND BEACH" }, "websiteUrl": "https://www.NetworkTokenMerchant.com", "acquirer": { "acquirerId": "40010052242", "acquirerMerchantId": "MerchantOrgID" } }, "networkTokenServices": { "visaTokenService": { "enrollment": true }, "mastercardDigitalEnablementService": { "enrollment": true } } } } } } } } }}{ "id": "94498504004", "submitTimeUtc": "2024-07-01T16:25:20Z", "status": "SUCCESS", "registrationInformation": { "mode": "COMPLETE", "boardingPackageId": "1168704004" }, "organizationInformation": { "organizationId": "{MerchantAccountOrgId}", "parentOrganizationId": "{PortfolioOrgId}" }, "message": "Request was processed successfully"}For the full set of required fields, see Enable TMS and Enroll in Network Tokenization for a New Merchant in the Merchant Boarding Developer Guide.
Enable TMS and Enroll in Network Tokenization for an Existing Merchant
Enable Token Management Service and enroll an existing merchant organization in network tokenization with Visa and Mastercard.
POST /boarding/v1/registrations
POST /boarding/v1/registrations
View API Sample Request
{ "registrationInformation": { "boardingFlow": "ADDPRODUCT" }, "organizationInformation": { "organizationId": "yourmerchantorgidhere", "parentOrganizationId": "yourportfolioorgidhere", "type": "MERCHANT", "configurable": true, "businessInformation": { "name": "TokenMerchant", "address": { "country": "US", "address1": "123456 SandMarket", "locality": "ORMOND BEACH", "administrativeArea": "FL", "postalCode": "32176" }, "websiteUrl": "https://www.MerchantUrlHere.com", "businessContact": { "firstName": "Token", "lastName": "Man", "phoneNumber": "6574567813", "email": "[email protected]" } } }, "productInformation": { "selectedProducts": { "commerceSolutions": { "tokenManagement": { "subscriptionInformation": { "enabled": true }, "configurationInformation": { "configurations": { "vault": { "location": "GDC", "defaultTokenType": "CUSTOMER", "tokenFormats": { "customer": "32_HEX", "paymentInstrument": "32_HEX", "instrumentIdentifierCard": "19_DIGIT_LAST_4", "instrumentIdentifierBankAccount": "32_HEX" }, "sensitivePrivileges": { "cardNumberMaskingFormat": "FIRST_6_LAST_4" } }, "networkTokenEnrollment": { "businessInformation": { "name": "TokenMerchant", "doingBusinessAs": "NetworkTokenCo1", "address": { "country": "US", "locality": "ORMOND BEACH" }, "websiteUrl": "https://www.MerchantUrlHere.com", "acquirer": { "acquirerId": "40010052242", "acquirerMerchantId": "yourmerchantorgidhere" } }, "networkTokenServices": { "visaTokenService": { "enrollment": true }, "mastercardDigitalEnablementService": { "enrollment": true } } }, "networkTokenServices": { "notifications": { "enabled": true }, "paymentCredentials": { "enabled": true }, "visaTokenService": { "enableService": true, "enableTransactionalTokens": true }, "mastercardDigitalEnablementService": { "enableService": true, "enableTransactionalTokens": true } } } } } } } }}{ "id": "94498504004", "submitTimeUtc": "2024-07-01T16:25:20Z", "status": "SUCCESS", "registrationInformation": { "mode": "COMPLETE", "boardingPackageId": "1168704004" }, "organizationInformation": { "organizationId": "{MerchantAccountOrgId}", "parentOrganizationId": "{PortfolioOrgId}" }, "message": "Request was processed successfully"}For the full set of required fields, see Enable TMS and Enroll in Network Tokenization for an Existing Merchant in the Merchant Boarding Developer Guide.
Configure Your Merchant's Token Vault
Token Vault Management
Token vaults are where merchants store their customer and payment data. A internal user can enable the vault.
Vaults are assigned to an owner, and all data within the vault belongs to the owner. You can grant permission to individual MIDs to create, retrieve, update, and delete tokens within a vault. Created tokens belong to the owner of the vault, not the creator of the token. If you remove a MID from a vault, it can no longer access any tokens within that vault, including tokens created under that MID.
Configure Vault Settings
- Log in to the test environment or production environment:
- Test:
- Production:
In the left navigation panel, click the Token Management icon.
Click Vault Management New. The Vault Management page appears. From the Vault Owner drop-down list, select the vault owner.
In the Details column, click Vault Settings. The Edit Vault page appears.
Click Edit. A dialog box appears with a message to warn you that changing your vault settings could result in your merchants being unable to access tokens, which could result in failing transactions. Click Yes if you want to continue.
Enter the vault name, supported payment methods, supported token types and formats, card number masking format, payment instrument storing configuration, and the webhook URL. For each token type, you can choose from these token formats:
- 32 Character Hex
- 22 Digits
- 19 Digits Luhn Check Passing
- 16 Digits Luhn Check Passing
- Click SAVE.
To return to the vault management page, click VAULT MANAGEMENT.
Configure Vault Access
- Log in to the test environment or production environment:
- Test:
- Production:
In the left navigation panel, click the Token Management icon.
Click Vault Management New. The Vault Management page appears.
Select the vault owner that you want to configure from the Vault Owner drop-down list.
In the Details column, click Access Settings. The MID Access page appears.
Check the box for the vault settings you want to enable for each merchant you want to configure:
- Visa Token
- Mastercard Token
- Card Unmasked
- Create
- Update
- Retrieve
- Click Submit to save your settings.
Enable Network Tokenization
Network tokenization replaces a customer's primary account number (PAN) with a network token. A network token is a tokenized card number that is issued by card networks (for example, Visa, Mastercard, American Express, and Discover). Network tokens use the same format as a PAN but are domain-restricted and cryptographically secured. This reduces exposure to fraud and data breaches.
For more information about how network tokens work and their benefits, see Network Tokens.
Network token enablement is currently a manual process and requires a request to be sent to support. For more information about network token enablement, visit the Support Center:
Configure Network Tokenization by Card Type
Token Requestor IDs
A token requestor ID (TRID) is a unique identifier that entities such as merchants use to request network tokens from token providers. Having a TRID is a prerequisite for enabling network tokenization.
Visa and Mastercard TRIDs
An internal user can enroll a merchant as a VISA or Mastercard token requestor through the .
When the enrollment is submitted, the relationship ID and token requestor ID appear on the page for Visa Token Service (VTS) and the token requestor ID appears for Mastercard.
To request a TRID from the token provider, uses merchant business details already stored. If any of the details are not present, a dialog form should appear prompting you to complete the missing information.
American Express TRIDs
Enrollment as a token requestor for American Express is a manual process. Contact your representative to request the TRID for American Express.
Allow 2 to 3 days for the completion of your request.
Each entity must register with the token provider to get a TRID. Contact a Cybersource representative to enroll a merchant as a token requestor.
- Log in to the test environment or production environment:
- Test:
- Production:
In the left navigation panel, click the Token Management icon.
Click Vault Management New. The Vault Management page appears.
Select the vault owner that you want to configure from the Vault Owner drop-down list.
In the Details column, click Network Tokenization. The Network Tokenization page appears.
Configure your network tokenization settings for each supported card type:
a. On the VISA tab, switch the Enroll to VISA Token Services button to On to enable Visa token services.
The required business information for the merchant will be populated:
- Merchant name - Website URL - Country code
b. Click Onboard with Acquirer ID and enter the required information:
- Acquirer ID: Set the value to 40010052242. This is a static acquirer ID that is used for . - Acquirer merchant ID: Enter your organization ID.
c. Click Manage Details.
d. Check Enable Visa Token Provisioning to enable Visa network token provisioning.
e. Check Enable Visa Token Transactions to enable Visa transaction processing using network tokens.
f. Enter the token requestor ID (TRID) and relationship ID if necessary.
g. Click Submit to save your settings.
a. On the MASTERCARD tab, switch the Enroll to MASTERCARD Token Services button to On to enable Mastercard token services.
b. Click Manage Details.
c. Check Enable Mastercard Token Provisioning to enable Mastercard network token provisioning.
d. Check Enable Mastercard Token Transactions to enable Mastercard transaction processing using network tokens.
e. Enter the token TRID and relationship ID if necessary.
f. Click Submit to save your settings.
a. On the AMERICAN EXPRESS tab, switch the Enroll to AMERICAN EXPRESS Token Services button to On to enable American Express token services.
b. Check Enable American Express Token Provisioning to enable American Express network token provisioning.
c. Check Enable American Express Token Transactions to enable American Express transaction processing using network tokens.
d. Enter the token TRID and SE number if necessary.
e. Click Submit to save your settings.
Tokenize Payment Information
For details on authenticating and constructing requests to the API, see Requesting the Token Management Service.
Store Customer Payment Details
Create a customer token with validated payment details by including TOKEN_CREATE in a payment authorization request.
POST /pts/v2/payments
POST /pts/v2/payments
View API Sample Request
{ "clientReferenceInformation": { "code": "TC50171_3" }, "processingInformation": { "commerceIndicator": "internet", "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer", "paymentInstrument", "shippingAddress" ] }, "orderInformation": { "billTo": { "country": "US", "lastName": "Deo", "address1": "201 S. Division St.", "postalCode": "48104-2201", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "John", "email": "{% t key="test-email" /%}" }, "amountDetails": { "totalAmount": "102.00", "currency": "USD" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "4895379987X11515", "securityCode": "089", "expirationMonth": "12" } }}{ "id": "6760630088136127303955", "status": "AUTHORIZED", "orderInformation": { "amountDetails": { "authorizedAmount": "102.00", "currency": "USD" } }, "tokenInformation": { "instrumentidentifierNew": false, "instrumentIdentifier": { "state": "ACTIVE", "id": "7030000000014911515" }, "shippingAddress": { "id": "F45FB3E443AF3C57E053A2598D0A9CFF" }, "paymentInstrument": { "id": "F45FC6785E3C31A2E053A2598D0A5346" }, "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }}The response returns a customer token along with the payment instrument, shipping address, and instrument identifier tokens created for the transaction. Use the customer token ID in paymentInformation.customer.id to authorize subsequent payments without resending card details.
For the full set of required fields, response fields, and related operations, see Payments with Customer Tokens.
Authorize a payment with an existing customer token. To create a customer token first, see Manage Customer Tokens.
POST /pts/v2/payments
POST /pts/v2/payments
View API Sample Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F45FB3E443AC3C57E053A2598D0A9CFF" } }, "orderInformation": { "amountDetails": { "currency": "USD", "totalAmount": "10.00" } }}{ "id": "7055928871556818104953", "status": "AUTHORIZED", "orderInformation": { "amountDetails": { "authorizedAmount": "10.00", "currency": "USD" } }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111", "state": "ACTIVE" }, "paymentInstrument": { "id": "0F35E9CFEA463E34E063A2598D0A3FC2" }, "customer": { "id": "B21E6717A6F03479E05341588E0A303F" } }}For the full set of required fields, response fields, and related operations, see Payments with Customer Tokens.
Retrieve a Customer Token
Retrieve the details of an existing customer token.
GET /tms/v2/customers/{customerTokenId}
GET /tms/v2/customers/{customerTokenId}
View API Sample Request
{ "_links": { "self": { "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078" }, "paymentInstruments": { "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments" }, "shippingAddresses": { "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses" } }, "id": "F2F3ADA770102B51E053A2598D0A9078", "buyerInformation": { "merchantCustomerID": "Your customer identifier", "email": "{% t key="test-email" /%}" }, "clientReferenceInformation": { "code": "TC50171_3" }, "merchantDefinedInformation": [ { "name": "data1", "value": "Your customer data" } ], "metadata": { "creator": "testrest" }}The {customerTokenId} is the customer token ID returned in the id field when you created the customer token. For details, see Manage Customer Tokens.
Delete a Customer Token
Remove a customer token that you no longer need.
DELETE /tms/v2/customers/{customerTokenId}
DELETE /tms/v2/customers/{customerTokenId}
View API Sample Request
DELETE /tms/v2/customers/{customerTokenId}A successful delete response returns an empty HTTP 204 No Content status. For details, see Manage Customer Tokens.
Provision a Network Token
Provision a network token directly for a card number using the Tokenized Cards API.
POST /tms/v2/tokenized-cards
POST /tms/v2/tokenized-cards
View API Sample Request
{ "source": "ONFILE", "card": { "number": "X622943123116478", "expirationMonth": "12", "expirationYear": "2026" }}{ "_links": { "self": { "href": "/tms/v2/tokenized-cards/518CA1611EF98697E063AF598E0ADFB9" }, "instrumentIdentifier": { "href": "/tms/v1/instrumentidentifiers/7031530000033441624" } }, "id": "518CA1611EF98697E063AF598E0ADFB9", "object": "tokenizedCard", "state": "ACTIVE", "paymentAccountReference": "V0010013025104530884197510742", "number": "489537XXXXXX1624", "type": "visa", "card": { "suffix": "6478", "expirationMonth": "12", "expirationYear": "2026" }, "source": "ONFILE"}For the full set of required fields, response fields, and related operations, see Network Tokens.
Process a Payment Using a Token
After a merchant creates a customer token linked to a payment instrument, that token can be used to authorize, capture, and refund payments without resending card details.
Process a Payment Using a Token
Authorize a payment using an existing customer token.
POST /pts/v2/payments
POST /pts/v2/payments
View API Sample Request
{ "clientReferenceInformation": { "code": "12345678" }, "paymentInformation": { "customer": { "id": "F60328413BAB09A4E053AF598E0A33DB" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" } }}{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6778647071126384904953/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6778647071126384904953" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6778647071126384904953/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6778647071126384904953", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentInformation": { "instrumentIdentifier": { "id": "7020000000010603216", "state": "ACTIVE" }, "shippingAddress": { "id": "F60328413BAE09A4E053AF598E0A33DB" }, "paymentInstrument": { "id": "F6032841BE33098EE053AF598E0AB0A5" }, "customer": { "id": "F60328413BAB09A4E053AF598E0A33DB" } }, "processingInformation": { "paymentSolution": "014" }, "processorInformation": { "approvalCode": "831000", "networkTransactionId": "0602MCC603474", "responseCode": "00" }, "reconciliationId": "EUHW1EMHIZ3O", "status": "AUTHORIZED", "submitTimeUtc": "2023-03-03T17:31:48Z"}For the full set of required fields, response fields, and related operations, see Payments with Customer Tokens.
Capture a Payment
To capture an authorization, include the request ID from the authorization in the URL for the capture request, along with the amount details in the request body.
View API Sample Request
{ "clientReferenceInformation": { "code": "ABC123" }, "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } }}{ "_links": { "void": { "method": "POST", "href": "/pts/v2/captures/6662994431376681303954/voids" }, "self": { "method": "GET", "href": "/pts/v2/captures/6662994431376681303954" } }, "clientReferenceInformation": { "code": "1666299443215" }, "id": "6662994431376681303954", "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } }, "reconciliationId": "66535942B9CGT52U", "status": "PENDING", "submitTimeUtc": "2022-10-20T20:57:23Z"}For the full set of required fields and an example request and response, see Captures.
Refund a Payment
To refund a payment, include the request ID from the authorization in the URL for the refund request, along with the amount details in the request body.
View API Sample Request
{ "orderInformation": { "amountDetails": { "totalAmount": "100.00", "currency": "EUR" } }}{ "_links": { "void": { "method": "POST", "href": "/pts/v2/credits/6699964581696622603955/voids" }, "self": { "method": "GET", "href": "/pts/v2/credits/6699964581696622603955" } }, "clientReferenceInformation": { "code": "1669996458298" }, "creditAmountDetails": { "currency": "eur", "creditAmount": "100.00" }, "id": "6699964581696622603955", "orderInformation": { "amountDetails": { "currency": "EUR" } }, "reconciliationId": "61873329OAILG3Q6", "status": "PENDING", "submitTimeUtc": "2022-12-02T15:54:18Z"}For the full set of required fields and an example request and response, see Refunds.
Subscribe to Network Token Updates
Create a digital signature key, then create a webhook subscription to receive notifications about network token lifecycle events, such as provisioning, updates, and device binding.
Create a Digital Signature Key
You must create a digital signature key to enable to send notifications to your servers.
POST /kms/egress/v2/keys-sym
POST /kms/egress/v2/keys-sym
{ "clientRequestAction": "CREATE", "keyInformation": { "provider": "nrtd", "tenant": "merchantName", "keyType": "sharedSecret", "organizationId": "merchantName" }}{ "submitTimeUtc": "2021-03-17T06:53:06+0000", "status": "SUCCESS", "keyInformation": { "provider": "NRTD", "tenant": "merchantName", "organizationId": "merchantName", "keyId": "bdc0fe52-091e-b0d6-e053-34b8d30a0504", "key": "u3qgvoaJ73rLJdPLTU3moxrXyNZA4eo5dklKtIXhsAE=", "keyType": "sharedSecret", "status": "Active", "expirationDate": "2022-03-17T06:53:06+0000" }}Create a Webhook Subscription
Subscribe to network token lifecycle event notifications.
POST /notification-subscriptions/v1/webhooks
POST /notification-subscriptions/v1/webhooks
View API Sample Request
{ "organizationId": "merchantOrgId", "productId": "tokenManagement", "url": "https://www.yoursite.com/webhooks/tms/notifications", "eventTypes": [ "tms.networktoken.provisioned", "tms.networktoken.updated", "tms.networktoken.binding" ]}{ "submitTimeUtc": "2023-04-12T10:15:30+0000", "status": "SUCCESS", "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationId": "merchantOrgId", "productId": "tokenManagement", "url": "https://www.yoursite.com/webhooks/tms/notifications", "eventTypes": [ "tms.networktoken.provisioned", "tms.networktoken.updated", "tms.networktoken.binding" ]}Get Details on a Webhook Subscription
Retrieve the details of an existing webhook subscription.
GET /notification-subscriptions/v1/webhooks/{webhookID}
GET /notification-subscriptions/v1/webhooks/{webhookID}
View API Sample Request
{ "submitTimeUtc": "2023-04-12T10:15:30+0000", "status": "SUCCESS", "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationId": "merchantOrgId", "productId": "tokenManagement", "url": "https://www.yoursite.com/webhooks/tms/notifications", "eventTypes": [ "tms.networktoken.provisioned", "tms.networktoken.updated", "tms.networktoken.binding" ]}For details on retrieving, updating, and deleting webhook subscriptions, see Webhooks.
Thanks for your feedback!
Last published: September 29, 2026