Partner Detokenization

As a partner, in order to request the de-tokenization of a token created by another partner you need:

• To know the token id
• To authenticate to the de-tokenization webservice as a partner
• To be in the list of the authorized detokenizers that was given when the token was created.

Authentication

The authentication is very similar to the merchant one, the header matches the following pattern:

X-Wsse: AuthToken PartnerAPILogin="{partnerLogin}", PasswordDigest="{digest}", Nonce="{b64nonce}", Created="{timestamp}"

Where:

• partnerLogin is your API login, provided by SysPay, along with a shared passphrase
• b64nonce is a base64-encoded random token (nonce) generated for each request
• timestamp is the current unix timestamp
• digest is a string generated from the nonce, the timestamp and the passphrase with the following algorithm:

BASE64(BINARY_SHA1(NONCE + TIMESTAMP + PASSPHRASE))

This header can only be used once and must be re-generated on each request.

Example code (PHP)

<?php

function generateHeaders($partnerLogin, $passphrase, $nonce = null, $timestamp = null) {
  $nonce = null === $nonce ? md5(rand(), true) : $nonce;
  $timestamp = null === $timestamp ? time() : $timestamp;

  $digest = base64_encode(sha1($nonce . $timestamp . $passphrase, true));
  $b64nonce = base64_encode($nonce);

  $header = sprintf('X-Wsse: AuthToken PartnerAPILogin="%s", PasswordDigest="%s", Nonce="%s", Created="%d"',
                      $partnerLogin, $digest, $b64nonce, $timestamp);

  return $header;
}

If called with the following parameters:

<?php

generateHeaders("myPartnerLogin", "myPartnerPassphrase", "my random nonce", 1400000000)

You would expect the following output::

X-Wsse: AuthToken PartnerAPILogin="myPartnerLogin", PasswordDigest="yxag0yx38DPpCDx1Pl8UZnmXANE=", Nonce="bXkgcmFuZG9tIG5vbmNl", Created="1400000000"

Detokenization request

This method allows a partner to detokenize a token that was created by a merchant and which he was authorizated to de-tokenize. The response includes a one-time-use redirect URL, to which the user has to be redirected to in order to view the payment method details.

Notes:

• The generated URL can only be accessed once and it has a timed access limit of 60 seconds after it has been requested. (If it’s expired, you should request another one)
• As this URL will let you access sensitive card details, it is important to consider it as such, it should not be stored and it should only be communicated through a secure channel.

URL syntax:/api/{version}/partner/token/{token.id}/detokenize Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
type	string	TEXT|IMAGE	Y	The returned detokenization type. IMAGE refers to payment method details returned as an image. TEXT is payment method details shown as pure text. Please check which type you are allowed to use.
viewer	string	max length 100	Y	Details of the user that will be viewing the detokenized data.
company_reference	string	max length 100	Y	The merchant/hotel registration reference (in your system) for whom you are going to detokenize the token.

Example request

{
    "type": "IMAGE",
    "viewer": "John Doe",
    "company_reference": "4242"
}

Response parameters

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be detokenize.
redirect_url	string	Y	The url from where to access the detokenized card details.

Example response

{
   "class":"detokenize",
   "redirect_url":"http:\/\/www.syspay.com\/redirect\/detokenize\/a448bc2a-9d97-11e4-a460-1ed32635ba79"
}