> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/xpay-enablement/ja/api-rifarensu/tsp-api-v1/kitsp/tkun-api.md).
# トークン発行・管理 API
[TSP-API-OUT-v1-Provisioning-Management-oas2.yaml](https://openapi.gitbook.com/o/fwy1mtbRONGA2YDKDBr0/spec/TSP-API-OUT-v1-Provisioning-Management-oas2.yaml)
## POST /tokens
> This method is used by TSH to request the creation of a new token.
````json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Create Token"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens":{"post":{"summary":"POST /tokens","description":"This method is used by TSH to request the creation of a new token.","operationId":"createToken","parameters":[{"$ref":"#/components/parameters/x-request-id-header"}],"responses":{"200":{"description":"createToken response payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/createTokenRes"}}}},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 115, 163, 164, 166, 167, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Create Token"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createTokenReq"}}},"description":"createToken request payload","required":true}}}},"components":{"parameters":{},"schemas":{"createTokenRes":{"type":"object","required":["tokenId","tokenInfo"],"properties":{"tokenId":{"$ref":"#/components/schemas/tokenId"},"tokenInfo":{"$ref":"#/components/schemas/tokenInfo"}}},"tokenId":{"maxLength":48,"minLength":1,"type":"string","description":"Unique Token Identifier"},"tokenInfo":{"type":"object","description":"Token related information","properties":{"exp":{"$ref":"#/components/schemas/exp"},"last4":{"$ref":"#/components/schemas/last4"},"encryptedData":{"type":"string","description":"**Only applicable to ECOM tokens**
\n\nThe token credentials data encrypted with JWE format (https://datatracker.ietf.org/doc/html/rfc7516) using following encryption parameters:
\n* JWE base64url encoded string\n* \"alg\" (Algorithm) header parameter: ECDH-ES\n* \"enc\" (Encryption Algorithm) header parameter: A256GCM\n* \"kid\" (Key ID) header parameter: Key identifier corresponding to EC public key of the recipient\n* EC curve: P-256\nThe JSON object that is encrypted is defined as follows:\n\n|JSON field parameter name|description|MOC|Length|\n|-------|-------|-------|-------|\n|dpan|The token PAN value|M|Up to 19|\n|exp|The token expiry date in the format MMYY|M|4| \n\n**Example**: ```{\"dpan:\"9580981500100002\", \"exp\":\"1222\"}```"}}},"exp":{"type":"string","maxLength":4,"minLength":4,"description":"Token expiry date in MMYY format"},"last4":{"type":"string","maxLength":4,"minLength":4,"description":"Last digits of the token pan value"},"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"createTokenReq":{"type":"object","required":["issuerId","cardRefId","tokenRequestorId"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"cardRefId":{"$ref":"#/components/schemas/cardRefId"},"walletProviderId":{"$ref":"#/components/schemas/walletProviderId"},"cipheredCardInfo":{"$ref":"#/components/schemas/cipheredCardInfo"},"publicKeyIdentifier":{"type":"string","minLength":1,"maxLength":32,"description":"Identifier of the key used to encrypt cipheredCardInfo.
Provided by TSP to Thales during onboarding."},"tokenProductId":{"$ref":"#/components/schemas/tokenProductId"},"tokenRequestorId":{"$ref":"#/components/schemas/tokenRequestorId"},"merchantGatewayId":{"description":"Unique identifier of the merchant gateway.
Applicable to ECOM only.","$ref":"#/components/schemas/merchantGatewayId"},"tokenStorageId":{"$ref":"#/components/schemas/tokenStorageId"},"deviceInfo":{"$ref":"#/components/schemas/deviceInfo"},"reusedTokenId":{"$ref":"#/components/schemas/reusedTokenId"},"initialState":{"$ref":"#/components/schemas/initialState"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"cardRefId":{"maxLength":64,"minLength":1,"type":"string","description":"A unique identifier of the issuer that aims to identify the funding card.
\nThis parameter is provided by the TSH.
\nUpon configuration it corresponds either to issuerCardRefId or walletCardRefId (e.g. for ApplePay, it corresponds to the FPANID in such case)"},"walletProviderId":{"maxLength":32,"minLength":1,"type":"string","description":"Wallet Provider identifier, defined by Thales
For:
\n- Apple Pay, the value is 'APPLE_PAY'\n- Samsung Pay HCE/TEE, the value is 'SPAYHCE'\n- Android Pay, the value is 'ANDROID_PAY'\n- For other wallet (such as HCE Wallet), id is provided during on-boarding phase\nValue always provided except for ECOM.\n"},"cipheredCardInfo":{"maxLength":8196,"minLength":1,"type":"string","description":"TSH sends card information as JSON encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:
\n* The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.\n* The key encryption algorithm is either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.
\nThe key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
\nIt is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new TSPs.\n* The encryption result is then encoded using base64.
\n* The public key length in the certificate can be 2048-bit or 4096-bit.\n\nOnce deciphered, the card info contains the following information:
\n\n|JSON field parameter name|description|MOC|Length|\n|-------|-------|-------|-------|\n|fpan|The funding pan to digitize|M|Up to 19|\n|exp|The expiry date in the format MMYY|O|4|\n|cvv|Depending of the OEM, this value is provided or not|O|3 or 4|\n|additionalCardInfos| Optional JSON Open format, in order to add additional card info - project dependent|O|Up to 8177|\n\n\n*Note: If not provided, the TSP must rely on the cardRefId provided to find the funding card to digitize from its token vault.*\n
"},"tokenProductId":{"maxLength":48,"minLength":1,"type":"string","description":"ID of the token product (Identify token domain). \n\nAs the token products are mapped to Issuer card products, the values shall be defined at the begining of the project with the TSP."},"tokenRequestorId":{"maxLength":48,"minLength":1,"type":"string","description":"ID of the token requestor in the format expected by the TSP"},"merchantGatewayId":{"type":"string","description":"Unique identifier of the merchant gateway.","minLength":10,"maxLength":10},"tokenStorageId":{"maxLength":64,"minLength":1,"type":"string","description":"Token storage unique identifier (also known as deviceId or applicationId).
\nIndicates the storage in which the token has been digitized.
\nFor ApplePay, it corresponds to the device SEID.
\nNot applicable for ECOM."},"deviceInfo":{"type":"object","description":"Device related information. Provides information about the device in which token has been digitized.
Not applicable for ECOM.","properties":{"deviceName":{"maxLength":128,"minLength":1,"type":"string","description":"device name
The name associated by the end user to the device."},"brand":{"maxLength":16,"minLength":1,"type":"string","description":"device brand"},"model":{"maxLength":16,"minLength":1,"type":"string","description":"device model"},"type":{"type":"string","minLength":1,"maxLength":16,"description":"device type
Possible values are:PHONETABLETWATCHCOMPUTERREALITYUNKNOWN"}}},"reusedTokenId":{"maxLength":48,"minLength":1,"type":"string","description":"The tokenId provided in case the Wallet Provider wants to re-use an existing token"},"initialState":{"type":"string","description":"Initial state of the token when created.
Default value is SUSPENDED","enum":["ACTIVE","SUSPENDED"]}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
````
## PUT /tokens/{tokenId}/cardInfo
> This method is used by TSH to request the update of funding pan information of the token
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Update Card Data"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens/{tokenId}/cardInfo":{"put":{"summary":"PUT /tokens/{tokenId}/cardInfo","description":"This method is used by TSH to request the update of funding pan information of the token","operationId":"updateToken","parameters":[{"$ref":"#/components/parameters/x-request-id-header"},{"$ref":"#/components/parameters/tokenIdPath"}],"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 163, 166, 432, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Update Card Data"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateTokenReq"}}},"description":"updateToken request payload","required":true}}}},"components":{"parameters":{"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}},"schemas":{"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"updateTokenReq":{"type":"object","required":["newCipheredCardInfo","issuerId"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"newCipheredCardInfo":{"$ref":"#/components/schemas/newCipheredCardInfo"},"publicKeyIdentifier":{"type":"string","minLength":1,"maxLength":32,"description":"Identifier of the key used to encrypt newCipheredCardInfo.
Provided by TSP to Thales during onboarding."},"newCardRefId":{"$ref":"#/components/schemas/cardRefId"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"newCipheredCardInfo":{"maxLength":8196,"minLength":1,"type":"string","description":"TSH sends new card information as JSON encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:
\n* The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.\n* The key encryption algorithm is either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.
\nThe key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
\nIt is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new TSPs.\n* The encryption result is then encoded using base64.
\n* The public key length in the certificate can be 2048-bit or 4096-bit.\n\nOnce deciphered, the card info contains the following information:
\n\n|JSON field parameter name|description|MOC|Length|\n|-------|-------|-------|-------|\n|newFpan|The new funding pan value to update|O|Up to 19|\n|newExp|The new expiry date in the format MMYY|O|4|\n|newAdditionalCardInfos| Optional JSON Open format, in order add/update/delete additional card info - project dependent|O|Up to 8177|\n\n*Note: At least one of the three JSON fields needs to be provided.*"},"cardRefId":{"maxLength":64,"minLength":1,"type":"string","description":"A unique identifier of the issuer that aims to identify the funding card.
\nThis parameter is provided by the TSH.
\nUpon configuration it corresponds either to issuerCardRefId or walletCardRefId (e.g. for ApplePay, it corresponds to the FPANID in such case)"}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
## PUT /tokens/{tokenId}/state
> This method is used by TSH to request the update of token state
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Update Token State"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens/{tokenId}/state":{"put":{"summary":"PUT /tokens/{tokenId}/state","description":"This method is used by TSH to request the update of token state","operationId":"updateTokenState","parameters":[{"$ref":"#/components/parameters/x-request-id-header"},{"$ref":"#/components/parameters/tokenIdPath"}],"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 432, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Update Token State"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateTokenStateReq"}}},"description":"updateTokenState request payload","required":true}}}},"components":{"parameters":{"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}},"schemas":{"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"updateTokenStateReq":{"type":"object","required":["newState","issuerId"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"newState":{"$ref":"#/components/schemas/state"},"reason":{"$ref":"#/components/schemas/reason"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"state":{"type":"string","description":"state of the token","enum":["SUSPENDED","DELETED","ACTIVE","ERASED"]},"reason":{"maxLength":16,"minLength":1,"type":"string","description":"The reason of the state update\n\nPossible values are:\n\n|reason code|description|\n|-------|-------|\n|11001|Activation from user interaction|\n|21001|Activation initiated by the issuer|\n|21002|Deletion initiated by the issuer| \n|11002|Deletion initiated by the user|\n|21003|Suspension initiated by the issuer| \n|11003|Suspension initiated by the user|\n|21004|Resumption initiated by the issuer| \n|11004|Resumption initiated by the user|\n"}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
## GET /issuers/{issuerId}/tokens/{tokenId}/credentials
> This method is used by TSH to request the credentials of an existing token.
````json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Get Token Credentials"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/issuers/{issuerId}/tokens/{tokenId}/credentials":{"get":{"summary":"GET /issuers/{issuerId}/tokens/{tokenId}/credentials","description":"This method is used by TSH to request the credentials of an existing token.","operationId":"getTokenCredentials","parameters":[{"$ref":"#/components/parameters/x-request-id-header"},{"$ref":"#/components/parameters/issuerIdPath"},{"$ref":"#/components/parameters/tokenIdPath"}],"responses":{"200":{"description":"getTokenCredentials response payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getTokenCredentialsRes"}}}},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 115, 163, 164, 166, 167, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Get Token Credentials"]}}},"components":{"parameters":{"issuerIdPath":{"schema":{"type":"string","maxLength":10,"minLength":10},"description":"Identifier of the issuer","in":"path","name":"issuerId","required":true},"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}},"schemas":{"getTokenCredentialsRes":{"type":"object","required":["encryptedData"],"properties":{"encryptedData":{"type":"string","description":"The token credentials data encrypted with JWE format (https://datatracker.ietf.org/doc/html/rfc7516) using following encryption parameters:
\n* JWE base64url encoded string\n* \"alg\" (Algorithm) header parameter: ECDH-ES\n* \"enc\" (Encryption Algorithm) header parameter: A256GCM\n* \"kid\" (Key ID) header parameter: Key identifier corresponding to EC public key of the recipient\n* EC curve: P-256\nThe JSON object that is encrypted is defined as follows:\n\n|JSON field parameter name|description|MOC|Length|\n|-------|-------|-------|-------|\n|dpan|The token PAN value|M|Up to 19|\n|exp|The token expiry date in the format MMYY|M|4| \n|fpan|The funding PAN value|M|Up to 19|\n|fpanExp|The funding PAN expiry date in the format MMYY|M|4|\n|paymentAccountReference|The payment account reference|O|29| \n|serviceCode|The service code used in track2 data|O|3|\n|psn|The token PAN sequence number|O|2|\n**Example**: ```{\"dpan:\"9580981500100002\", \"exp\":\"1232\", \"fpan\":\"9680981500100003\", \"fpanExp\":\"1230\", \"paymentAccountReference\":\"23R0PAYMENTACCOUNTREFERENCEXX\", \"serviceCode\":\"123\", \"psn\":\"01\"}```"}}},"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
````
## POST /tokens/{tokenId}/replenishment
> This method is used by TSH, in case of HCE, to request replenishment of payment credentials in the mobile wallet.\
\
> This API only applies to TSH Pay solution (Issuer HCE wallet).
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Request Replenishment"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens/{tokenId}/replenishment":{"post":{"summary":"POST /tokens/{tokenId}/replenishment","description":"This method is used by TSH, in case of HCE, to request replenishment of payment credentials in the mobile wallet.
\nThis API only applies to TSH Pay solution (Issuer HCE wallet).","operationId":"requestReplenishment","parameters":[{"$ref":"#/components/parameters/x-request-id-header"},{"$ref":"#/components/parameters/tokenIdPath"}],"responses":{"200":{"description":"requestReplenishment response payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/requestReplenishmentRes"}}}},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 119, 432, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Request Replenishment"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/requestReplenishmentReq"}}},"description":"requestReplenishment request payload","required":true}}}},"components":{"parameters":{"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}},"schemas":{"requestReplenishmentRes":{"type":"object","required":["repCounter","paymentCredsData"],"properties":{"repCounter":{"$ref":"#/components/schemas/repCounter"},"usageLimits":{"$ref":"#/components/schemas/usageLimits"},"paymentCredsData":{"$ref":"#/components/schemas/paymentCredsData"}}},"repCounter":{"type":"string","maxLength":5,"description":"Value of the replenishment counter for the last replenishment."},"usageLimits":{"type":"object","properties":{"maxPayments":{"type":"number","minimum":0,"maximum":999999,"description":"Max number of payments allowed with the payment credential.\nApply to LUK payment credentials only.\n"},"expiryDate":{"type":"string","maxLength":10,"minLength":10,"description":"Expiry date in ISO 8601 format YYYY-MM-DD"}}},"paymentCredsData":{"type":"array","items":{"type":"object","required":["encPaymentCredData","paymentCredAttr","diversifiers"],"properties":{"encPaymentCredData":{"type":"object","description":"Encrypted data containing the concatened payment credentials values.","required":["encType","encData"],"properties":{"encData":{"type":"string","maxLength":8096,"description":"Encrypted data in base64"},"encType":{"type":"string","enum":["RAW","JWE"],"description":"Encryption Type:\nRAW: encryption of raw binary data. Encrypted data are encoded in base 64.\nJWE: JWE encryption with JWS signature. Signed and Encrypted data are encoded in compact serialization format.\n"},"rawEncParams":{"$ref":"#/components/schemas/rawEncParams"}}},"paymentCredAttr":{"$ref":"#/components/schemas/paymentCredAttr"},"diversifiers":{"type":"array","items":{"$ref":"#/components/schemas/diversifier"}}}}},"rawEncParams":{"type":"object","description":"Raw information related to the encryption type","required":["algo","mode"],"properties":{"algo":{"type":"string","enum":["3DES","AES"]},"mode":{"type":"string","enum":["ECB","CBC","CCM","GCM"]},"padding":{"type":"string","enum":["ISO_7816"],"description":"Present when there is mandatory padding on data."},"iv":{"type":"string","maxLength":32,"description":"Initialization vector encoded in base 64."},"aeadNonce":{"type":"string","maxLength":128,"description":"Nonce value encoded in base 64 for AEAD modes of encryption (CCM or GCM)"},"aeadMac":{"type":"string","maxLength":128,"description":"MAC value encoded in base 64 for AEAD modes of encryption (CCM or GCM)"},"keyId":{"type":"string","maxLength":32,"description":"Encryption key identifier"}}},"paymentCredAttr":{"type":"object","required":["type"],"description":"Since the status apply to all payment credentials variants and payment channels, the type is set but not the code nor the channel.","properties":{"type":{"type":"string","description":"Payment credential type","enum":["SUK","LUK"]},"code":{"type":"string","description":"Payment credential code to identify a variant of payment credential\n* SUK_IDN (Mastercard)\n* SUK_UMD (Mastercard)\n* SUK_MD (Mastercard)\n* SUK_AC (Pure)\n* SUK_LC (Pure)\n* SUK_CPIN (Pure)\nWhen present, it means the attributes apply to a specific variant. Otherwise, the attributes apply to all variants.\n","enum":["SUK_IDN","SUK_UMD","SUK_MD","SUK_AC","SUK_LC","SUK_CPIN"]},"channel":{"type":"string","enum":["CONTACTLESS","REMOTE"],"description":"Payment channel\nWhen present, it means the attributes apply to a specific payment channel. Otherwise, the attributes apply to all channels.\n"},"dki":{"type":"string","maxLength":2,"description":"Derived key index."}}},"diversifier":{"type":"string","maxLength":7,"description":"Payment credential diversifier:\n* For an SUK, this is an ATC which is a string of 4 hexa digits.\n* For an LUK, this is an \"YHHHHCC\" Visa CBP diversifier which is a string of 7 digits.\n"},"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"requestReplenishmentReq":{"type":"object","required":["issuerId","atc","usageLimitsStatus","paymentCredsStatus","lastRepCounter"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"atc":{"$ref":"#/components/schemas/atc"},"usageLimitsStatus":{"$ref":"#/components/schemas/usageLimitsStatus"},"paymentCredsStatus":{"$ref":"#/components/schemas/paymentCredsStatus"},"lastRepCounter":{"$ref":"#/components/schemas/repCounter"},"schemeTranRecords":{"$ref":"#/components/schemas/schemeTranRecords"},"schemeTranRecSig":{"$ref":"#/components/schemas/schemeTranRecSig"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"atc":{"type":"string","maxLength":4,"minLength":4,"description":"Value of the application transaction counter that will be used in the next payment transaction.\nThe ATC is encoded as an hexa string on 4 digits.\n"},"usageLimitsStatus":{"type":"object","properties":{"paymentCredRemaining":{"type":"number","minimum":0,"maximum":999999,"description":"Number of payment credentials remaining.\nApply to SUK payment credentials only.\n"},"paymentRemaining":{"type":"number","minimum":0,"maximum":999999,"description":"Number of payments remaining.\nApply to LUK payment credentials only.\n"},"expiryDate":{"type":"string","maxLength":10,"minLength":10,"description":"Expiry date in ISO 8601 format YYYY-MM-DD"}}},"paymentCredsStatus":{"type":"array","items":{"type":"object","required":["diversifier","timestamp","paymentCredAttr"],"properties":{"sukStatus":{"type":"string","enum":["USED_FOR_CONTACTLESS","USED_FOR_REMOTE","UNUSED","DISCARDED"],"description":"SUK Payment credential status\nPresent when payment credential type is SUK.\nThe status apply to all payment credentials variants.\n"},"diversifier":{"$ref":"#/components/schemas/diversifier"},"timestamp":{"type":"string","maxLength":30,"description":"Timestamp in ISO 8601 format: YYYY-MM-DD'T'HH:MM:SS\n* LUK: Time of creation of the payment credentail status data.\n* SUK with status UNUSED or DISCARDED: Time of creation of the payment credentail status data.\n* SUK with status USED_FOR_CONTACTLESS or USED_FOR_REMOTE: Time the payment credential was used.\n"},"paymentCredAttr":{"$ref":"#/components/schemas/paymentCredAttr"}}}},"schemeTranRecords":{"type":"string","maxLength":2000,"description":"Transaction records for the last transactions as specified by the payment scheme.\nThe transaction records data is encoded in base 64.\n"},"schemeTranRecSig":{"type":"string","maxLength":200,"description":"Signature of the transaction records computed according to the scheme specifications and encoded in hexa."}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
## PUT /tokens/{tokenId}/replenishment/status
> This method is used by TSH, in case of HCE, to notify the TSP the replenishment of payment credentials has been completed in the mobile wallet.\
\
> This API only applies to TSH Pay solution (Issuer HCE wallet).
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Notify Replenishment Result"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens/{tokenId}/replenishment/status":{"put":{"summary":"PUT /tokens/{tokenId}/replenishment/status","description":"This method is used by TSH, in case of HCE, to notify the TSP the replenishment of payment credentials has been completed in the mobile wallet.
\nThis API only applies to TSH Pay solution (Issuer HCE wallet).\n","operationId":"replenishmentDone","parameters":[{"$ref":"#/components/parameters/x-request-id-header"},{"$ref":"#/components/parameters/tokenIdPath"}],"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 119, 432, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Notify Replenishment Result"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/replenishmentDoneReq"}}},"description":"replenishmentDone request payload","required":true}}}},"components":{"parameters":{"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}},"schemas":{"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"replenishmentDoneReq":{"type":"object","required":["issuerId","repCounter"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"repCounter":{"$ref":"#/components/schemas/repCounter"},"usageLimits":{"$ref":"#/components/schemas/usageLimits"},"diversifiers":{"type":"array","items":{"$ref":"#/components/schemas/diversifier"}}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"repCounter":{"type":"string","maxLength":5,"description":"Value of the replenishment counter for the last replenishment."},"usageLimits":{"type":"object","properties":{"maxPayments":{"type":"number","minimum":0,"maximum":999999,"description":"Max number of payments allowed with the payment credential.\nApply to LUK payment credentials only.\n"},"expiryDate":{"type":"string","maxLength":10,"minLength":10,"description":"Expiry date in ISO 8601 format YYYY-MM-DD"}}},"diversifier":{"type":"string","maxLength":7,"description":"Payment credential diversifier:\n* For an SUK, this is an ATC which is a string of 4 hexa digits.\n* For an LUK, this is an \"YHHHHCC\" Visa CBP diversifier which is a string of 7 digits.\n"}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
## PUT /tokens/{tokenId}/newData/status
> This method is used by TSH to inform the TSP about the token re-personalization result in case of token renewal.
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Notify Token Reperso Result"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens/{tokenId}/newData/status":{"put":{"summary":"PUT /tokens/{tokenId}/newData/status","description":"This method is used by TSH to inform the TSP about the token re-personalization result in case of token renewal.\n","operationId":"submitNewTokenDataStatus","parameters":[{"$ref":"#/components/parameters/x-request-id-header"},{"$ref":"#/components/parameters/tokenIdPath"}],"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Notify Token Reperso Result"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/submitNewTokenDataStatus"}}},"description":"submitNewTokenDataStatus request payload","required":true}}}},"components":{"parameters":{"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}},"schemas":{"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"submitNewTokenDataStatus":{"type":"object","required":["issuerId","status"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"status":{"type":"string","enum":["SUCCESS","FAILED","EXPIRED"]},"error":{"type":"object","description":"Present in case the status is FAILED","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"|Error code | Description|\n|-------|-------|\n|911|Operation failed|\n|321|Operation on token already on-going|\n|921|Unexpected server error|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
## GET /healthCheck
> This method is used by TSH to monitor TSP health. It should be used every 30 seconds in production environment.
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Healthcheck"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/healthCheck":{"get":{"summary":"GET /healthCheck","description":"This method is used by TSH to monitor TSP health. It should be used every 30 seconds in production environment.","operationId":"healthCheck","parameters":[{"$ref":"#/components/parameters/x-request-id-header"}],"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 911, 921"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Healthcheck"]}}},"components":{"parameters":{},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
## POST /tokens/{tokenId}/reperso
> This request is triggered when TSH has to repersonalize a token and requires all the data elements associated.\
> \
> After this request, TSP shall recover all the existing elements and submit it to the TSH through \[Submit New Token Data]\(
> \
> TSH will callback TSP through the \[Notify Token Reperso Result]\() to notify the profile has been pushed to the device with success. At this moment, TSP shall set the ATC to zero to sync with the ATC personalized in the device.
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Reperso Token"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens/{tokenId}/reperso":{"post":{"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 321, 432, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"description":"This request is triggered when TSH has to repersonalize a token and requires all the data elements associated.\n\nAfter this request, TSP shall recover all the existing elements and submit it to the TSH through [Submit New Token Data](https://next.stoplight.io/gdigital/tsh-token-requestor-tsp-api/version%2F1.0/tsh-tr-tsp-api-incoming.oas2.yml?view=%2Fsubmit-new-token-data%2Fsubmitnewtokendata).\n\nTSH will callback TSP through the [Notify Token Reperso Result](https://next.stoplight.io/gdigital/tsh-token-requestor-tsp-api/version%2F1.0/tsh-tr-tsp-api-outgoing.oas2.yml?view=%2Fnotify-token-reperso-result%2Fsubmitnewtokendatastatus) to notify the profile has been pushed to the device with success. At this moment, TSP shall set the ATC to zero to sync with the ATC personalized in the device.","summary":"POST /tokens/{tokenId}/reperso","operationId":"repersoToken","tags":["Reperso Token"],"parameters":[{"schema":{"type":"string","maxLength":48,"minLength":1},"in":"header","name":"x-request-id","required":true,"description":"Unique request identifier use to trace function calls across system"},{"$ref":"#/components/parameters/tokenIdPath"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/repersoTokenReq"}}},"description":"repersoToken body request"}}}},"components":{"schemas":{"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"repersoTokenReq":{"type":"object","properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"newTokenProductId":{"$ref":"#/components/schemas/tokenProductId"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"tokenProductId":{"maxLength":48,"minLength":1,"type":"string","description":"ID of the token product (Identify token domain). \n\nAs the token products are mapped to Issuer card products, the values shall be defined at the begining of the project with the TSP."}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}},"parameters":{"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}}}}
```
## POST /listTokens
> This method is used by TSH to request the list of tokens associated to either a funding PAN, a card reference ID or a token PAN.\
> In case of a search by token PAN, the list returned by TSP shall contain 1 element at most.
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"List Tokens"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/listTokens":{"post":{"summary":"POST /listTokens","description":"This method is used by TSH to request the list of tokens associated to either a funding PAN, a card reference ID or a token PAN.\nIn case of a search by token PAN, the list returned by TSP shall contain 1 element at most.\n","operationId":"listTokens","parameters":[{"$ref":"#/components/parameters/x-request-id-header"}],"responses":{"200":{"description":"listTokens response payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/listTokensRes"}}}},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 166, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["List Tokens"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/listTokensReq"}}},"description":"listTokens request payload","required":true}}}},"components":{"parameters":{},"schemas":{"listTokensRes":{"type":"object","properties":{"tokenList":{"description":"list of tokens associated to the funding PAN","type":"array","items":{"type":"object","properties":{"tokenId":{"$ref":"#/components/schemas/tokenId"},"exp":{"$ref":"#/components/schemas/exp"},"last4":{"$ref":"#/components/schemas/last4"},"state":{"$ref":"#/components/schemas/cciState"},"tokenStorageId":{"$ref":"#/components/schemas/tokenStorageId"},"tokenRequestorId":{"$ref":"#/components/schemas/tokenRequestorId"},"walletProviderId":{"$ref":"#/components/schemas/walletProviderId"},"deviceInfo":{"$ref":"#/components/schemas/deviceInfo"},"creationDate":{"type":"string","format":"date-time","description":"Token creation date.
ISO 8601 format: YYYY-MM-DDThh:mm:ssTZD"}},"required":["tokenId","exp","last4","state","tokenStorageId","tokenRequestorId","walletProviderId"]}}}},"tokenId":{"maxLength":48,"minLength":1,"type":"string","description":"Unique Token Identifier"},"exp":{"type":"string","maxLength":4,"minLength":4,"description":"Token expiry date in MMYY format"},"last4":{"type":"string","maxLength":4,"minLength":4,"description":"Last digits of the token pan value"},"cciState":{"type":"string","description":"state of the token","enum":["SUSPENDED","DELETED","ACTIVE","INACTIVE"]},"tokenStorageId":{"maxLength":64,"minLength":1,"type":"string","description":"Token storage unique identifier (also known as deviceId or applicationId).
\nIndicates the storage in which the token has been digitized.
\nFor ApplePay, it corresponds to the device SEID.
\nNot applicable for ECOM."},"tokenRequestorId":{"maxLength":48,"minLength":1,"type":"string","description":"ID of the token requestor in the format expected by the TSP"},"walletProviderId":{"maxLength":32,"minLength":1,"type":"string","description":"Wallet Provider identifier, defined by Thales
For:
\n- Apple Pay, the value is 'APPLE_PAY'\n- Samsung Pay HCE/TEE, the value is 'SPAYHCE'\n- Android Pay, the value is 'ANDROID_PAY'\n- For other wallet (such as HCE Wallet), id is provided during on-boarding phase\nValue always provided except for ECOM.\n"},"deviceInfo":{"type":"object","description":"Device related information. Provides information about the device in which token has been digitized.
Not applicable for ECOM.","properties":{"deviceName":{"maxLength":128,"minLength":1,"type":"string","description":"device name
The name associated by the end user to the device."},"brand":{"maxLength":16,"minLength":1,"type":"string","description":"device brand"},"model":{"maxLength":16,"minLength":1,"type":"string","description":"device model"},"type":{"type":"string","minLength":1,"maxLength":16,"description":"device type
Possible values are:PHONETABLETWATCHCOMPUTERREALITYUNKNOWN"}}},"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"listTokensReq":{"type":"object","properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"},"cipheredCardInfo":{"$ref":"#/components/schemas/cciCipheredCardInfo"},"cipheredTokenInfo":{"$ref":"#/components/schemas/cciCipheredTokenInfo"},"cardRefId":{"$ref":"#/components/schemas/cardRefId"},"publicKeyIdentifier":{"type":"string","minLength":1,"maxLength":32,"description":"Identifier of the key used to encrypt cipheredCardInfo.
Provided by TSP to Thales during onboarding."}},"required":["issuerId"]},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"},"cciCipheredCardInfo":{"maxLength":8196,"minLength":1,"type":"string","description":"TSH sends card information as JSON encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:
\n* The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.\n* The key encryption algorithm is either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.
\nThe key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
\nIt is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new TSPs.\n* The encryption result is then encoded using base64.
\n* The public key length in the certificate can be 2048-bit or 4096-bit.\n\nOnce deciphered, the card info contains the following information:
\n\n|JSON field parameter name|description|MOC|Length|\n|-------|-------|-------|-------|\n|fpan|The funding pan|M|Up to 19|"},"cciCipheredTokenInfo":{"maxLength":8196,"minLength":1,"type":"string","description":"TSH sends token information as JSON encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:
\n* The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.\n* The key encryption algorithm is either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.
\nThe key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.
\nIt is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new TSPs.\n* The encryption result is then encoded using base64.
\n* The public key length in the certificate can be 2048-bit or 4096-bit.\n\nOnce deciphered, the card info contains the following information:
\n\n|JSON field parameter name|description|MOC|Length|\n|-------|-------|-------|-------|\n|dpan|The token PAN|M|Up to 19|"},"cardRefId":{"maxLength":64,"minLength":1,"type":"string","description":"A unique identifier of the issuer that aims to identify the funding card.
\nThis parameter is provided by the TSH.
\nUpon configuration it corresponds either to issuerCardRefId or walletCardRefId (e.g. for ApplePay, it corresponds to the FPANID in such case)"}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
## POST /tokens/{tokenId}/replenish
> This request is triggered when TSH has to replenish a token.\
\
> This API only applies to Google Pay solution.
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Replenish Token"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens/{tokenId}/replenish":{"post":{"responses":{"200":{"description":"replenishToken response payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/replenishTokenRes"}}}},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 321, 432, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"description":"This request is triggered when TSH has to replenish a token.
\nThis API only applies to Google Pay solution.","summary":"POST /tokens/{tokenId}/replenish","operationId":"replenishToken","tags":["Replenish Token"],"parameters":[{"schema":{"type":"string","maxLength":48,"minLength":1},"in":"header","name":"x-request-id","required":true,"description":"Unique request identifier use to trace function calls across system"},{"$ref":"#/components/parameters/tokenIdPath"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/replenishTokenReq"}}},"description":"replenishToken body request"}}}},"components":{"schemas":{"replenishTokenRes":{"type":"object","properties":{"kekLabel":{"type":"string","description":"Label of the key used to encrypt paymentKeys"},"kekKcv":{"type":"string","description":"KCV of the Key Encryption Key"},"paymentKeys":{"type":"string","description":"String representation of JSON array of objects containing payment keys
as defined in Data Preparation section"}}},"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"replenishTokenReq":{"type":"object","properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}},"parameters":{"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}}}}
```
## PUT /tokens/{tokenId}/replenish/done
> This method is used by TSH to inform the TSP that the token replenishment has been done.\
\
> This API only applies to Google Pay solution.
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Notify Token Replenish Done"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/tokens/{tokenId}/replenish/done":{"put":{"summary":"PUT /tokens/{tokenId}/replenish/done","description":"This method is used by TSH to inform the TSP that the token replenishment has been done.
\nThis API only applies to Google Pay solution.","operationId":"notifyReplenishTokenDone","parameters":[{"$ref":"#/components/parameters/x-request-id-header"},{"$ref":"#/components/parameters/tokenIdPath"}],"responses":{"204":{"description":"successful"},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 119, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Notify Token Replenish Done"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/notifyReplenishTokenDone"}}},"description":"notifyReplenishTokenDone request payload","required":true}}}},"components":{"parameters":{"tokenIdPath":{"schema":{"type":"string","maxLength":48,"minLength":1},"description":"Identifier of the token","in":"path","name":"tokenId","required":true}},"schemas":{"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"notifyReplenishTokenDone":{"type":"object","required":["issuerId"],"properties":{"issuerId":{"$ref":"#/components/schemas/issuerId"}}},"issuerId":{"maxLength":10,"minLength":10,"type":"string","description":"Unique Identifier of Issuer
"}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
## POST /merchant-gateways/{merchantGatewayId}/merchants
> This method is used by TSH to request the creation of a new merchant.
```json
{"openapi":"3.1.1","info":{"title":"TSH Token Requestor Outgoing API","version":"1.3.5"},"tags":[{"name":"Create Merchant"}],"servers":[{"url":"/tsp/trapi/v1.0"}],"paths":{"/merchant-gateways/{merchantGatewayId}/merchants":{"post":{"summary":"POST /merchant-gateways/{merchantGatewayId}/merchants","description":"This method is used by TSH to request the creation of a new merchant.","operationId":"createMerchant","parameters":[{"$ref":"#/components/parameters/x-request-id-header"},{"$ref":"#/components/parameters/merchantGwIdPath"}],"responses":{"200":{"description":"createMerchant response payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/createMerchantRes"}}}},"400":{"description":"Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.
Possible error codes are 111, 112, 113, 115, 163, 164, 166, 167, 911, 921","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorRes"}}}},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}},"tags":["Create Merchant"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createMerchantReq"}}},"description":"createMerchant request payload","required":true}}}},"components":{"parameters":{"merchantGwIdPath":{"schema":{"type":"string","maxLength":10,"minLength":10},"description":"Identifier of the merchant gateway","in":"path","name":"merchantGatewayId","required":true}},"schemas":{"createMerchantRes":{"type":"object","required":["merchantId"],"properties":{"merchantId":{"$ref":"#/components/schemas/merchantId"}}},"merchantId":{"type":"string","description":"Merchant ID generated by TSP.
It is computed as per EMVCo TRID format.","minLength":11,"maxLength":11},"errorRes":{"type":"object","description":"Error Information Response","required":["responseCode"],"properties":{"responseCode":{"type":"number","description":"Error Response code to the request\n|Error code | Description| Retryable|\n|-------|-------|-------|\n|111|Missing mandatory parameter|N|\n|112|Bad parameter format|N|\n|113|Unknown issuer|N|\n|115|Unknown product|N|\n|119|Unknown Token|N|\n|163|Product not supported for mobile payment|N|\n|164|FPAN Digitization Count Exceeded|N|\n|166|Invalid FPAN|N|\n|167|Card already enrolled|N|\n|321|Operation on token already on-going|N|\n|322|Time to live of the operation expired|N|\n|431|Invalid perso data|N|\n|432|Current token state does not allow this operation|N|\n|911|Operation failed|N|\n|921|Unexpected server error|Y|\n"},"errorMessage":{"type":"string","description":"Textual error message"}}},"createMerchantReq":{"type":"object","required":["merchantName"],"properties":{"merchantName":{"$ref":"#/components/schemas/merchantName"}}},"merchantName":{"type":"string","description":"An unique merchant name that is end user friendly.","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9-_. ]+$"}},"responses":{"500":{"description":"Internal Server Error\nRetry possible\n"},"503":{"description":"Service Unavailable\nRetry possible\n"}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.payments.thalescloud.io/xpay-enablement/ja/api-rifarensu/tsp-api-v1/kitsp/tkun-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.