Provisioning and Management API

Request to check digital card account eligibility

post

This method is used by wallet server to check that a card account is eligible for provisioning.

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardAccountDescriptorobjectRequired

The Card Account Descriptor.Depending on cardSource, it shall be formatted as follows:

For ON-FILE:"cardAccountDescriptor" : {"walletCardAccountId" : "1234"}
For USER-INPUT, CLIENT-SDK and READER-MODE:"cardAccountDescriptor" : {"opaqueCardAccountData" : "data returned by Issuer backend to Wallet"}

cardSourcestring · enumOptionalPossible values:

Responses

200

checkCardAccount response payload

application/json

termsAndConditionsIdstring · max: 64Optional

Unique identifier of the T&C to be presented to the end user. If T&Cs are not required, all 0's should be returned. getAsset API will be used to retrieve the T&Cs content.

cardArtManifeststring[]Optional

Array of GUIDs required to build card art. Each cart art can be retrieved using getAsset API with corresponding GUID.

500

Internal Server Error

post

/checkCardAccount

POST /checkCardAccount HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 288

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "issuerId": "text",
  "cardAccountDescriptor": {},
  "device": {
    "seId": "text",
    "deviceType": "PHONE",
    "language": "text",
    "phoneNumberLastDigits": "text",
    "deviceName": "text"
  },
  "cardSource": "ON-FILE"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "termsAndConditionsId": "text",
  "cardArtManifest": [
    "text"
  ]
}

Request to fetch an asset

post

This method is used by Wallet Server to fetch the content of an asset.

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

guidstring · max: 64Required

Responses

200

getAsset response payload

application/json

contentTypestring · enumOptionalPossible values:

500

Internal Server Error

post

/getAsset

POST /getAsset HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "guid": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "contentType": "icon",
  "content": {
    "mimeType": "image/pdf",
    "encodedData": "text",
    "width": "text",
    "height": "text"
  }
}

Request to provision a digital card

post

This method is used by wallet server to provision a digital card to user's device.

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

cardAccountDescriptorobjectRequired

The Card Account Descriptor.Depending on cardSource, it shall be formatted as follows:

For ON-FILE:"cardAccountDescriptor" : {"walletCardAccountId" : "1234"}
For USER-INPUT, CLIENT-SDK and READER-MODE:"cardAccountDescriptor" : {"opaqueCardAccountData" : "data returned by Issuer backend to Wallet"}

walletAccountIdstring · min: 1 · max: 128Required

The Wallet Account Identifier. Unique for each wallet account.

cardLastDigitsstring · min: 4 · max: 5Optional

The Card last 4 or 5 digits.

cryptoOTPstring · max: 3096Optional

Cryptographic OTP computed by Issuer backend and returned to the wallet during enrolment. It will be checked by TSH if it's provided.

Responses

200

provisionCard response payload

application/json

walletCardIdstring · min: 1 · max: 64Optional

The Wallet Card Identifier. Unique for each wallet card.

walletCardAccountIdstring · min: 1 · max: 64Optional

The Wallet Card Account Identifier. Unique for each wallet card account.

500

Internal Server Error

post

/provisionCard

POST /provisionCard HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 667

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "issuerId": "text",
  "cardAccountDescriptor": {},
  "ssdDescriptor": {
    "aid": "text",
    "appletInstanceAid": "text",
    "apduResponse": "text",
    "counter": "text",
    "casdCertificate": "text",
    "spsdCertificateSerialNumber": "text"
  },
  "walletAccountId": "text",
  "device": {
    "seId": "text",
    "deviceType": "PHONE",
    "language": "text",
    "phoneNumberLastDigits": "text",
    "deviceName": "text"
  },
  "walletScoring": {
    "color": "GREEN",
    "deviceScore": 1,
    "accountScore": 1,
    "phoneNumberScore": 1,
    "reasonCodes": [
      "text"
    ]
  },
  "customerData": {
    "dateOfBirth": "2026-06-08",
    "customerId": "text"
  },
  "cardLastDigits": "text",
  "cryptoOTP": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "walletCardId": "text",
  "walletCardAccountId": "text",
  "cardDescriptor": {
    "appletCurrencyCode": "text",
    "displayCardNumber": "text",
    "cardholderName": "text",
    "cardArtManifest": [
      "text"
    ],
    "labelColor": "text",
    "shortDescription": "text",
    "longDescription": "text",
    "privacyPolicyURL": "text",
    "termsAndConditionsURL": "text",
    "contactWebsite": "text",
    "contactEmail": "text",
    "contactNumber": "text",
    "contactName": "text",
    "cardActions": {
      "minLoadedBalance": 1,
      "maxLoadedBalance": 1,
      "minLoadAmount": 1,
      "maxLoadAmount": 1
    },
    "commutePlans": [
      {
        "identifier": "text",
        "title": [
          {
            "label": "text",
            "value": "text",
            "language": "text"
          }
        ],
        "usage": {
          "label": "Usage",
          "value": [
            {
              "text": "text",
              "language": "text"
            }
          ]
        },
        "validityPeriod": {
          "startDate": "2026-06-08T19:58:51.926Z",
          "expiryDate": "2026-06-08T19:58:51.926Z",
          "dateStyle": "SHORT",
          "timeStyle": "SHORT"
        }
      }
    ],
    "mobileApp": {
      "identifier": "text",
      "action": "text",
      "intentExtraText": "text"
    }
  }
}

Request to suspend, resume or delete/park a digital card

post

This method is used by Wallet Server to request a suspend, resume or park/delete a virtual card.

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

issuerIdstring · min: 1 · max: 16Required

The Card Issuer Identifier. Unique for each card issuer.

walletCardIdstring · min: 1 · max: 64Required

The Wallet Card Identifier. Unique for each wallet card.

operationstring · enumRequired

The operation to perform on the card. Note: - PARK is to be used for an already provisioned card. - Whereas DELETE is to be used for failed provisioning.

Possible values:

Responses

200

manageCard response payload

application/json

500

Internal Server Error

post

/manageCard

POST /manageCard HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 167

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "issuerId": "text",
  "walletCardId": "text",
  "operation": "SUSPEND"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Callback to sendScript request

post

This method is used by Wallet server to provide a callback to a previous sendScript sent by TSH.

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

taskIdstring · min: 1 · max: 64Required

Unique task identifier used to correlate a callback to a request.

Responses

200

sendScriptCallback response payload

application/json

500

Internal Server Error

post

/sendScriptCallback

POST /sendScriptCallback HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 196

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "taskId": "text",
  "apduResponses": [
    {
      "rApdu": "text",
      "messageId": "text",
      "messageName": "text"
    }
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Callback to updateCard request

post

This method is used by Wallet server to provide a callback to a previous updateCard sent by TSH.

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

taskIdstring · min: 1 · max: 64Required

Unique task identifier used to correlate a callback to a request.

statusCodenumberRequired

Status code to the request

Status code	Description
0	OK
911	Operation failed
921	Unexpected server error

statusMessagestringOptional

Textual status message

Responses

200

updateCardCallback response payload

application/json

500

Internal Server Error

post

/updateCardCallback

POST /updateCardCallback HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 159

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "taskId": "text",
  "statusCode": 1,
  "statusMessage": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  }
}

Request to get the current status of a digital card

post

This method is used by Wallet Server to the current status of a digital card.

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

walletCardIdstring · min: 1 · max: 64Required

The Wallet Card Identifier. Unique for each wallet card.

Responses

200

getCardStatus response payload

application/json

statestring · enumOptionalPossible values:

500

Internal Server Error

post

/getCardStatus

POST /getCardStatus HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "walletCardId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "state": "CREATED"
}

Request to get the current status of a card account

post

This method is used by Wallet Server to the current status of a card account.

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

walletCardAccountIdstring · min: 1 · max: 64Required

The Wallet Card Account Identifier. Unique for each wallet card account.

Responses

200

getCardAccountStatus response payload

application/json

statestring · enumOptional

The card account state

Possible values:

500

Internal Server Error

post

/getCardAccountStatus

POST /getCardAccountStatus HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "walletCardAccountId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "state": "ACTIVE",
  "accountBalance": {
    "balanceAmount": 1,
    "balanceCurrencyCode": "text",
    "balanceDate": "2026-06-08T19:58:51.926Z"
  }
}

Request to provide the next list of commands to be executed for a specific card

post

This method is used to request the pending commands to be executed for a specific card. Device should keep coming back when: - HTTP 200 is returned with statusCode=0 and APDU commands are provided

or HTTP 500 is returned (until max number of retries is reached)
or TSH is not accessible (until max number of retries is reached)

Header parameters

x-podstring · max: 128Required

HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming. Subsequent API calls should be sent to this pod.

Body

modestring · enumOptional

It is needed in the first request only.

Possible values:

walletCardIdstring · min: 1 · max: 64Required

The Wallet Card Identifier. Unique for each wallet card.

Responses

200

getCardCommands response payload

application/json

500

Internal Server Error

post

/getCardCommands

POST /getCardCommands HTTP/1.1
x-pod: text
Content-Type: application/json
Accept: */*
Content-Length: 216

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z"
  },
  "mode": "PARK",
  "walletCardId": "text",
  "apduResponses": [
    {
      "rApdu": "text",
      "messageId": "text",
      "messageName": "text"
    }
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-08T19:58:51.926Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "apduCommands": [
    {
      "cApdu": "text",
      "messageId": "text",
      "messageName": "text"
    }
  ]
}

PreviousIncoming operations (to TSH)NextCard Notification API

Last updated 4 months ago

Was this helpful?