Skip to main content
Welcome to the preview portal — This is an early release of the new Doc Hub experience, with more content coming soon.

Requesting the Token Management Service

Before You Begin

Before requesting the API, you must already have a account. If you do not, you can create an evaluation account.

Authentication

To make requests to the API, you must authenticate every request using a JSON Web Signature (JWS) bearer token in the authorization HTTP header. The token construction process is the same regardless of key type — only the signing key differs.

Generate a Signing Key

Generate and download a P12 certificate in the : choose Payment Configuration > Key Management, then Generate Key > REST – Certificate.

Create a shared secret key pair in the : choose Payment Configuration > Key Management, click + Generate key, and choose REST – Shared Secret.

Construct the Authorization Header

The HTTP message header consists of three elements: content-type, host, and authorization. The authorization value is a JWS bearer token with three Base64URL-encoded segments separated by periods: Bearer <header>.<claims>.<signature>.

  1. Build the JWS header with alg: RS256, typ: JWT, and kid set to the serial number of your P12 certificate or shared secret key.

  2. Build the JWS claims:

    ClaimDescription
    digestA Base64-encoded SHA-256 hash of the request body. Omit for GET and DELETE requests.
    digestAlgorithmSet to SHA-256. Omit if digest is not included.
    expThe token expiration time, as a NumericDate value. Cannot exceed two minutes after iat.
    iatThe issued-at time, as a NumericDate value (seconds since the Unix epoch).
    issThe merchant ID that created the signing key.
    jtiA unique token ID, formatted as a UUID version 4, used for replay prevention.
    request-hostThe endpoint hostname, excluding the protocol and path.
    request-methodThe HTTP request method, lowercase (for example, post).
    request-resource-pathThe endpoint path, excluding the domain (for example, /tms/v2/customer).
    v-c-jwt-versionSet to 2.
    v-c-merchant-idYour transacting merchant ID.
    v-c-response-mle-kidThe message-level encryption response key ID, if message-level encryption is enabled.

  3. Sign the concatenated Base64URL-encoded header and claims using RSA-SHA256 with your private key, then Base64URL-encode the signature.

  4. Assemble the final token as <header>.<claims>.<signature> and send it in the Authorization: Bearer <jwt> header.

For complete instructions, see Set Up Custom Integration and choose either the P12 Certificate or Shared Secret Key Pair option.

Construct Your Request

Specify one of these hosts in the URL:

  • Test:
  • Production:

Append the resource, such as /tms/v2/customer to the host URL. For example, /tms/v2/customer.

Pass your request using an HTTP GET, POST, PATCH or DELETE method as specified in each API operation.

HTTP Response Headers

This HTTP response header indicates information about the tokenization result:

Response HeaderPossible ValuesDescription
instrumentidentifier-createdtrue or falseIndicates whether a new instrument identifier was created. For example, you have never tokenized this PAN or bank account, or an existing one was returned.

Understanding Token IDs and Case Sensitivity

Token IDs are not case sensitive. The following requests return the same resource:

GET /instrumentidentifiers/49C26351BF7D8765E05333B9d30AA9DB
GET /instrumentidentifiers/49c26351bf7d8765e05333b9d30aa9db

List matching rules:

  • Accept any case (web, WEB, WeB).
  • Store the expected case (WEB).
  • Return the expected case (WEB) metadata.

Metadata in Responses

Token type structures such as instrument identifiers and payment instruments contain a metadata map that contains data about the creator.

A metadata map is returned for every token type in a response to an HTTP POST, GET, and PATCH request.

Example metadata from a response:

"metadata": {  "creator": "mid1"}

PATCH Request Semantics

Patching within is based on JSON Merge Patch (RFC7396), in which changes follow the same structure being modified as that of a POST request, rather than JSON Patch (RFC6902), in which changes are expressed as a set of actions.

A PATCH request is different from a PUT request in that only the fields that must be changed need to be provided in the request, and those changes are merged with the existing record.

Here are some rules to consider:

  • When a field is to be removed, you can remove a field by entering a value of null.
  • When a field is set to null, and it does not exist in the current record, it is ignored.
  • You can remove groups of fields by setting the parent container to null.

Pagination

Responses can indicate pagination if you include the limit and offset fields in your request.

ParameterDescription
limitControls the maximum number of items that can be returned for a single request. The default is 20; the maximum is 100. If you set a limit greater than 100, a 400 Bad Request error results.
offsetControls the starting point within the collection of results. Defaults to 0. Setting a zero offset retrieves the first item in the collection. For example, if you have a collection of 15 items to be retrieved from a resource, and you specify limit=5, you can retrieve the entire set of results in three successive requests by varying the offset value: offset=0, offset=5, and offset=10. An offset greater than the number of results does not return an embedded object.

Pagination Response Header

HeaderDescription
X-total-countReturns total records count regardless of pagination.

Pagination Response Body Fields

FieldDescription
"object":"collection"Shows that the response is a collection of objects.
"offset": 40The offset parameter used in the request.
"limit": 20The limit parameter used in the request.
"count": 20The number of objects returned.
"total": 87The total number of objects.

Pagination Example

This example shows a request for objects 41 to 60.

Request:

GET /tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=40&limit=20

Response:

{  "_links": {    "self": {      "href": "/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=40&limit=20"    },    "first": {      "href": "/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=0&limit=20"    },    "prev": {      "href": "/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=20&limit=20"    },    "next": {      "href": "/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=60&limit=20"    },    "last": {      "href": "/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539399D30AAB2F/paymentinstruments?offset=80&limit=20"    }  },  "object":"collection",  "offset": 40,  "limit": 20,  "count": 20,  "total": 87,  "_embedded": {    // array data  }}

Last published: October 28, 2026

Not available for your audience

This page isn't available for your current audience selection.