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 using either HTTP signature authentication or JSON Web Token (JWT) authentication.

A Base64-encoded shared secret key is passed in the headers you generate for HTTP signature authentication.

Create a shared secret key pair in the : choose Payment Configuration > Key Management, click + Generate key, and choose REST – Shared Secret.
Set the required HTTP header fields: content-type, host, v-c-date, v-c-merchant-id, digest, and signature.
Calculate the digest header value: generate a SHA-256 hash of the request body, Base64-encode it, and prepend SHA-256=.
Calculate the signature hash: concatenate the required signature fields (v-c-date, digest, host, v-c-merchant-id, request-target) into a validation string, then generate a Base64-encoded HMAC SHA-256 hash of that string using your shared secret key.
Construct the signature header value using the keyid, algorithm, headers, and signature parameters.
Combine the HTTP headers with your HTTP message body to complete the request.

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

A P12 Certificate is passed in the headers you generate for JWT authentication.

Generate and download a P12 certificate in the : choose Payment Configuration > Key Management, then Generate Key > REST – Certificate.
Build the JWT header with alg: RS256, typ: JWT, kid set to the certificate serial number, and v-c-merchant-id set to your merchant ID.
Build the JWT claims with digest (a Base64-encoded SHA-256 hash of the request body, prefixed SHA-256=), digestAlgorithm: SHA-256, and iat (the issued-at time, in seconds).
Sign the concatenated Base64url-encoded header and claims using RSA-SHA256 with the private key from your P12 certificate, then Base64url-encode the signature.
Assemble the final JWT as <header>.<claims>.<signature> and send it in the Authorization: Bearer <jwt> header.

For complete instructions, see Set Up Custom Integration and choose the P12 Certificate 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 Header	Possible Values	Description
`instrumentidentifier-created`	`true` or `false`	Indicates 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.

Parameter Description

limit Controls 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.

offset Controls 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.

Parameter	Description
`limit`	Controls 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.
`offset`	Controls 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

Header	Description
`X-total-count`	Returns total records count regardless of pagination.

Pagination Response Body Fields

Field	Description
`"object":"collection"`	Shows that the response is a collection of objects.
`"offset": 40`	The offset parameter used in the request.
`"limit": 20`	The limit parameter used in the request.
`"count": 20`	The number of objects returned.
`"total": 87`	The 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  }}

Was this page helpful?

Last published: September 29, 2026