Outbound (to issuer)

notify issuer about any virtual card (token) change

post

This method is used by TSH to notify issuer in case a virtual card has been updated due to:

state change (activated/suspended/resumed/deleted)
belonging card updated

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier of a give session (enrolment session , Life Cycle Management session and other operation), used to link inbound and outbound requests of the same session together

x-issuer-idstring · min: 10 · max: 10Required

Unique identifier used to identify the issuer

Body

issuerCardRefIdstring · max: 48Required

The unique identifier of the funding card.This value is generated and managed by the issuer.This value can be updated in case of funding PAN replacement by the issuer.

virtualCardIdstring · min: 1 · max: 64Required

Unique identifier of the virtual card

walletProviderIdstring · min: 1 · max: 128Required

Wallet Provider identifier, defined by Thales:

walletProviderId	Description
APPLE_PAY	Apple Pay Wallet
ANDROID_PAY	Google Pay Wallet
SPAYHCE	Samsung Pay Wallet

walletCardRefIdstring · min: 1 · max: 128Optional

Card unique identifier defined by the Wallet Provider or the primary TSP.For ApplePay, it corresponds to the FPANID. For Fidesmo/Digiseq, it corresponds to the card identifier provided by the primary TSP.

walletVirtualCardIdstring · min: 1 · max: 128Optional

Wallet virtual card identifier.For ApplePay, it corresponds to the auxiliary DPANID.

primaryWalletVirtualCardIdstring · min: 1 · max: 128Optional

Primary wallet virtual card identifier.For ApplePay, it corresponds to the primary DPANID.

tokenStorageIdstring · min: 1 · max: 128Required

Unique token storage identifier

isPrimarybooleanRequired

It is a boolean information that inform if the virtual card is a primary virtual card or if it is an auxiliary virtual card. Always set to false in this API.

actionstring · enum · max: 128Optional

This corresponds to the action performed on the token

Here are the possible values:

ACTIVATE: When the virtual card is activated after provisioning.
SUSPEND: When the active virtual card is suspended.
RESUME: When the suspended virtual card is re-activated.
DELETE: When the virtual card deleted.
UPDATE: When the funding PAN value is updated (ex: card renewal).
ERASE: When a virtual card is erased following a GDPR action.

Possible values:

tokenInfostring · min: 1 · max: 8196Optional

Token information in JSON. This field is conditional to the TSP and provided only during enrolment.

This value is encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:

The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.
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. The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose. It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new issuers.
The encryption result is then encoded using base64.
The public key length in the certificate can be 2048-bit or 4096-bit.

Once deciphered, the cardInfo contains the following information:

JSON field parameter name	description	MOC	Length
pan	The token PAN.	M	Up to 19
exp	The expiry date in the format MMYY.	M	4

publicKeyIdentifierstring · min: 1 · max: 32Optional

Identifier of the key used to encrypt tokenInfo.Provided by Issuer to Thales during onboarding.

errorCodenumberOptional

Error code provided in case of operation failure initiated by the issuer

reason code	description
113	Unknown issuer
115	Unknown product
119	Unknown Token
221	The device was not reachable after retries
322	Time to live of the operation expired
911	Operation failed
921	Unexpected error

This list is not exhaustive. Error codes not listed shall be considered as a generic error.

sourcestring · enum · max: 32Required

The source actor that initiated the state change

Possible values:

Responses

200

Successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter

application/json

500

Internal Server Error

post

/notifyVirtualCardChange

POST /issuer/igwauxapi/notifyVirtualCardChange HTTP/1.1
Host: issuer.host.com
x-correlation-id: text
x-issuer-id: text
Content-Type: application/json
Accept: */*
Content-Length: 307

{
  "issuerCardRefId": "text",
  "virtualCardId": "text",
  "walletProviderId": "text",
  "walletCardRefId": "text",
  "walletVirtualCardId": "text",
  "primaryWalletVirtualCardId": "text",
  "tokenStorageId": "text",
  "isPrimary": false,
  "action": "ACTIVATE",
  "tokenInfo": "text",
  "publicKeyIdentifier": "text",
  "errorCode": 1,
  "source": "WALLET"
}

No content

check if Issuer is healthy

get

This method is used by TSH to monitor Issuer health

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier of a give session (enrolment session , Life Cycle Management session and other operation), used to link inbound and outbound requests of the same session together

x-issuer-idstring · min: 10 · max: 10Required

Unique identifier used to identify the issuer

Responses

204

Successful

No content

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter

500

Internal Server Error

get

/healthCheck

GET /issuer/igwauxapi/healthCheck HTTP/1.1
Host: issuer.host.com
x-correlation-id: text
x-issuer-id: text
Accept: */*

No content

request cobadge card digitization to the Issuer

post

This method is used by TSH exclusively to request the digitization of a cobadge card.

TSH will provide either cipheredCardInfo or (exclusive) cipheredTokenInfo or (exclusive) issuerCardRefId, depending on inputs from the Wallet provider.

The Issuer can still approve or reject the request. But the latter case will mostly happen in some limit, error cases, since the Wallet Provider will always trigger the cobadge digitization flow only in the case the digitization on the primary flow is approved.

In some exceptional error case scenarios that involve a retry from the end user or the Wallet Provider, the Issuer shall expect to receive the same request several times. Only the latest request has to be taken into account.

Header parameters

x-correlation-idstring · min: 1 · max: 64Required

Unique identifier of a give session (enrolment session , Life Cycle Management session and other operation), used to link inbound and outbound requests of the same session together

x-issuer-idstring · min: 10 · max: 10Required

Unique identifier used to identify the issuer

Body

cipheredCardInfostring · min: 1 · max: 8196Optional

The card information in JSON, encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:

The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.
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. The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose. It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new issuers.
The encryption result is then encoded using base64.
The public key length in the certificate can be 2048-bit or 4096-bit.

Once deciphered, the cardInfo contains the following information:

JSON field parameter name	description	MOC	Length
fpan	The funding pan to digitize	M	Up to 19
exp	The expiry date in the format MMYY	O	4
cvv	Depending of the OEM and scheme, this value is provided or not	O	3 or 4

Examples:

  Example 1
  {
    "fpan":"1234567891234567",
    "exp":"1218",
  }

  Example 2
  {
    "fpan":"1234567891234567",
    "exp":"1218",
    "cvv":"765"
  }

cipheredTokenInfostring · min: 1 · max: 8196Optional

The encrypted data contains the original token information used with primary TSP (Token for Token provisioning). This is only applicable for HCE Wallet. The original token information in JSON is encrypted using the PKCS#7 encryption. See encryption of cipheredCardInfo for more details. Once deciphered the tokenInfo contains the following information:

JSON field parameter name	description	MOC	Length
originalTokenRequestorId	Token Requestor Identifier of the original token provided and allocated by Scheme TSP	O	Up to 11
originalTokenId	The original token identifier as defined by the Scheme TSP.For VISA (VTS) it corresponds to vProvisionedTokenIDMandatory if originalToken is not provided.	C	Up to 64
originalToken	The original token used to request the digitization with primary TSPMandatory if originalTokenId is not provided.	C	Up to 19

publicKeyIdentifierstring · min: 1 · max: 32Optional

Identifier of the key used to encrypt cipheredCardInfo.Provided by Issuer to Thales during onboarding.

issuerCardRefIdstring · max: 48Optional

The unique identifier of the funding card.This value is generated and managed by the issuer.This value can be updated in case of funding PAN replacement by the issuer.

walletProviderIdstring · min: 1 · max: 128Required

Wallet Provider identifier, defined by Thales:

walletProviderId	Description
APPLE_PAY	Apple Pay Wallet
ANDROID_PAY	Google Pay Wallet
SPAYHCE	Samsung Pay Wallet

walletCardRefIdstring · min: 1 · max: 128Optional

Responses

200

requestCoBadgeDigitization response payload

application/json

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter

application/json

500

Internal Server Error

post

/requestCoBadgeDigitization

POST /issuer/igwauxapi/requestCoBadgeDigitization HTTP/1.1
Host: issuer.host.com
x-correlation-id: text
x-issuer-id: text
Content-Type: application/json
Accept: */*
Content-Length: 231

{
  "cipheredCardInfo": "text",
  "cipheredTokenInfo": "text",
  "publicKeyIdentifier": "text",
  "issuerCardRefId": "text",
  "walletProviderId": "text",
  "walletCardRefId": "text",
  "deviceInformation": {
    "tokenStorageId": "text",
    "tokenStorageType": "text"
  }
}

{
  "issuerCardRefId": "text",
  "paymentAccountReference": "text",
  "cipheredDomesticCard": "text",
  "publicKeyIdentifier": "text"
}

PreviousAPI reference - cobadged cards NextInbound (from issuer)

Last updated 4 months ago

Was this helpful?