Menu

Authentication

The third step is to authenticate the API.

Request headers

Include the following TMS-specific headers in all of your requests.

HeaderDescription
timeStampClient provided current time in UTC.
apiMerchantIdentifierMerchant identifier assigned by B2B Payments.
nonceA new random value sent in each request.
signatureClient generated signature sent in each request. See below for signature generation.
X-WP-Diagnostics-CorrelationIdOptional unique correlation Id from your system.

Example

Values are examples only.

Copied!
Accept:application/json
Content-Type: application/json
timeStamp: 2021-05-20T16: 20: 55Z
apiMerchantIdentifier: 296670d6-c7d5-4eb1-8f5f-8bb0e4f237a7
nonce: 0DCPbQxhJ
Signature: 9dfcbb5e9dbc83c056758e0c3ebb721409188fb04deda9703d4d80dde5306271
X-WP-Diagnostics-CorrelationId: {optional unique ID from your system}

Signature parameters

The following table defines the parameters used to generate the header Signature.

ParameterDescription
Merchant IdentifierMerchant identifier assigned by B2B Payments used in the apiMerchantIdentifier header.
Shared KeyShared key generated by the Merchant Portal. It is not included in the request message.
TimestampClient provided value submitted in the timestamp field of the header.
NonceClient generated value included in the nonce field of the header.
Request URITaken from request, the base URL and protocol/server are stripped.
Request MethodMethod name associated with the request, such as POST or GET.
PacketRequest body, field will be empty for GET request methods.

Signature elements layout

  • Each element of the signature is delimited by | (pipe character).

  • Data presented in proper order:
    MerchantRef + | SharedKey + | Timestamp + | Nonce + | RequestURI + | RequestMethod + | Packet

  • Data is on a single line (new lines and carriage return characters removed).

  • Timestamp in UTC (ISO 8601 to the second). For example, 2016-08-24T21:38:55Z

  • All alphabetical characters in UPPERCASE.

  • All whitespace is removed. For example, tabs and spaces.

  • Base64 encoded and SHA256 Hashed. No salt is used in hashing the data.

Signature examples

The following are step-by-step examples for generating a signature. Use the ingredients below to build up a signature, and then confirm that it matches the final signature in the example.

This process includes five steps:

  1. Build raw signature.
  2. Uppercase the entire raw signature.
  3. Remove all whitespace from uppercase raw signature.
  4. Convert the trimmed uppercase raw signature to Base64 string.
  5. Hash the base64 string using SHA256.

Ingredients

Note: If the profile contains spaces, make sure to send it with spaces, but replace the space with %20 when building the signature. For example:
api/Tokens/-E803-1111-CTDMRG8GAFPF2F?profileId=My%20Profile%20With%20Spaces&payloadType=Card

Copied!
merchantIdentifier = 57e988a9-f9b7-4e42-abc5-28fbad57d121
sharedKey = mySecretPassword
timestamp = 2021-07-01T14:47:08Z
nonce = 123abc
requestUrl = api/tokens
requestMethod = POST
requestPacket = {
    "cardDetails": {
        "cardNumber": "4111111111111111"
    },
    "outputTokenProviderProfileIds": [
        "MyProfile"
    ],
    "token": {
        "payloadType": "card"
    }
}
merchantIdentifier = 57e988a9-f9b7-4e42-abc5-28fbad57d121
sharedKey = mySecretPassword
timestamp = 2021-07-01T14:47:08Z
nonce = 123abc
requestUrl = api/Tokens/-E803-1111-CTDMRG8GAFPF2F?profileId=MyProfile&payloadType=Card
requestMethod = GET
requestPacket = // empty
merchantIdentifier = 57e988a9-f9b7-4e42-abc5-28fbad57d121
sharedKey = mySecretPassword
timestamp = 2021-07-01T14:47:08Z
nonce = 123abc
requestUrl = /api/Tokens/-E803-1111-CTDMRG8GAFPF2F?profileId=My Profile With Spaces&payloadType=Card
requestMethod = GET
requestPacket = // empty

1. Build raw signature.

Copied!
rawSignature = 57e988a9-f9b7-4e42-abc5-28fbad57d121|mySecretPassword|2021-07-01T14:47:08Z|123abc|api/tokens|POST|{
    "cardDetails": {
        "cardNumber": "4111111111111111"
    },
    "outputTokenProviderProfileIds": [
        "MyProfile"
    ],
    "token": {
        "payloadType": "card"
    }
}
rawSignature = 57e988a9-f9b7-4e42-abc5-28fbad57d121|mySecretPassword|2021-07-01T14:47:08Z|123abc|api/Tokens/-E803-1111-CTDMRG8GAFPF2F?profileId=MyProfile&payloadType=Card|GET|
rawSignature = 57e988a9-f9b7-4e42-abc5-28fbad57d121|mySecretPassword|2021-07-01T14:47:08Z|123abc|api/Tokens/-E803-1111-CTDMRG8GAFPF2F?profileId=My%20Profile%20With%20Spaces&payloadType=Card|GET|

2. Uppercase the entire raw signature.

Copied!
uppercaseRawSignature = 57E988A9-F9B7-4E42-ABC5-28FBAD57D121|MYSECRETPASSWORD|2021-07-01T14:47:08Z|123ABC|API/TOKENS|POST|{
    "CARDDETAILS": {
        "CARDNUMBER": "4111111111111111"
    },
    "OUTPUTTOKENPROVIDERPROFILEIDS": [
        "MYPROFILE"
    ],
    "TOKEN": {
        "PAYLOADTYPE": "CARD"
    }
}
uppercaseRawSignature = 57E988A9-F9B7-4E42-ABC5-28FBAD57D121|MYSECRETPASSWORD|2021-07-01T14:47:08Z|123ABC|API/TOKENS/-E803-1111-CTDMRG8GAFPF2F?PROFILEID=MYPROFILE&PAYLOADTYPE=CARD|GET|
uppercaseRawSignature = 57E988A9-F9B7-4E42-ABC5-28FBAD57D121|MYSECRETPASSWORD|2021-07-01T14:47:08Z|123ABC|API/TOKENS/-E803-1111-CTDMRG8GAFPF2F?PROFILEID=MY%20PROFILE%20WITH%20SPACES&PAYLOADTYPE=CARD|GET|

3. Remove all whitespace from uppercase raw signature.

Copied!
trimmedUppercaseRawSignature = 57E988A9-F9B7-4E42-ABC5-28FBAD57D121|MYSECRETPASSWORD|2021-07-01T14:47:08Z|123ABC|API/TOKENS|POST|{"CARDDETAILS":{"CARDNUMBER":"4111111111111111"},"OUTPUTTOKENPROVIDERPROFILEIDS":["MYPROFILE"],"TOKEN":{"PAYLOADTYPE":"CARD"}}
trimmedUppercaseRawSignature = 57E988A9-F9B7-4E42-ABC5-28FBAD57D121|MYSECRETPASSWORD|2021-07-01T14:47:08Z|123ABC|API/TOKENS/-E803-1111-CTDMRG8GAFPF2F?PROFILEID=MYPROFILE&PAYLOADTYPE=CARD|GET|
trimmedUppercaseRawSignature = 57E988A9-F9B7-4E42-ABC5-28FBAD57D121|MYSECRETPASSWORD|2021-07-01T14:47:08Z|123ABC|API/TOKENS/-E803-1111-CTDMRG8GAFPF2F?PROFILEID=MY%20PROFILE%20WITH%20SPACES&PAYLOADTYPE=CARD|GET|

4. Convert the trimmed uppercase raw signature to Base64 string.

Copied!
base64String = NTdFOTg4QTktRjlCNy00RTQyLUFCQzUtMjhGQkFENTdEMTIxfE1ZU0VDUkVUUEFTU1dPUkR8MjAyMS0wNy0wMVQxNDo0NzowOFp8MTIzQUJDfEFQSS9UT0tFTlN8UE9TVHx7IkNBUkRERVRBSUxTIjp7IkNBUkROVU1CRVIiOiI0MTExMTExMTExMTExMTExIn0sIk9VVFBVVFRPS0VOUFJPVklERVJQUk9GSUxFSURTIjpbIk1ZUFJPRklMRSJdLCJUT0tFTiI6eyJQQVlMT0FEVFlQRSI6IkNBUkQifX0=
base64String = NTdFOTg4QTktRjlCNy00RTQyLUFCQzUtMjhGQkFENTdEMTIxfE1ZU0VDUkVUUEFTU1dPUkR8MjAyMS0wNy0wMVQxNDo0NzowOFp8MTIzQUJDfEFQSS9UT0tFTlMvLUU4MDMtMTExMS1DVERNUkc4R0FGUEYyRj9QUk9GSUxFSUQ9TVlQUk9GSUxFJlBBWUxPQURUWVBFPUNBUkR8R0VUfA==
base64String = NTdFOTg4QTktRjlCNy00RTQyLUFCQzUtMjhGQkFENTdEMTIxfE1ZU0VDUkVUUEFTU1dPUkR8MjAyMS0wNy0wMVQxNDo0NzowOFp8MTIzQUJDfEFQSS9UT0tFTlMvLUU4MDMtMTExMS1DVERNUkc4R0FGUEYyRj9QUk9GSUxFSUQ9TVklMjBQUk9GSUxFJTIwV0lUSCUyMFNQQUNFUyZQQVlMT0FEVFlQRT1DQVJEfEdFVHw=

5. Hash the base64 string using SHA256.

Ensure that the final hashed string uses the lowercase representation of the hex characters.

Copied!
signature = 18d33c5b2d91a98a0612c2f956263597ae1609f503c6d8e269b6b449657b465d
signature = d6002963bb7475491f7aa0ca65df0ad7c53f5bda1d735dec1226fd638c187ca7
signature = 617d0eeeb0e8e3758e820ae15654943c03d54048da5a1a5367a673e7150c4fba