API de Aprovisionamiento y Gestión

WS-Transit-API-IN-oas2.yaml

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.

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

cardAccountDescriptorobject · cardAccountDescriptorRequerido

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 · enumOpcionalValores posibles:

Respuestas

200

checkCardAccount response payload

application/json

termsAndConditionsIdstring · máx: 64Opcional

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[]Opcional

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

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "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-17T17:31:51.466Z",
    "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.

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

guidstring · máx: 64Requerido

Respuestas

200

getAsset response payload

application/json

contentTypestring · enumOpcionalValores posibles:

500

Internal Server Error

post

/getAsset

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "guid": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z",
    "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.

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

cardAccountDescriptorobject · cardAccountDescriptorRequerido

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 · mín: 1 · máx: 128Requerido

The Wallet Account Identifier. Unique for each wallet account.

cardLastDigitsstring · mín: 4 · máx: 5Opcional

The Card last 4 or 5 digits.

cryptoOTPstring · máx: 3096Opcional

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

Respuestas

200

provisionCard response payload

application/json

walletCardIdstring · mín: 1 · máx: 64Opcional

The Wallet Card Identifier. Unique for each wallet card.

walletCardAccountIdstring · mín: 1 · máx: 64Opcional

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

500

Internal Server Error

post

/provisionCard

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "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-17",
    "customerId": "text"
  },
  "cardLastDigits": "text",
  "cryptoOTP": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z",
    "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-17T17:31:51.466Z",
          "expiryDate": "2026-06-17T17:31:51.466Z",
          "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.

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

issuerIdstring · mín: 1 · máx: 16Requerido

The Card Issuer Identifier. Unique for each card issuer.

walletCardIdstring · mín: 1 · máx: 64Requerido

The Wallet Card Identifier. Unique for each wallet card.

operationstring · enumRequerido

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.

Valores posibles:

Respuestas

200

manageCard response payload

application/json

500

Internal Server Error

post

/manageCard

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "issuerId": "text",
  "walletCardId": "text",
  "operation": "SUSPEND"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z",
    "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.

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

taskIdstring · mín: 1 · máx: 64Requerido

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

Respuestas

200

sendScriptCallback response payload

application/json

500

Internal Server Error

post

/sendScriptCallback

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "taskId": "text",
  "apduResponses": [
    {
      "rApdu": "text",
      "messageId": "text",
      "messageName": "text"
    }
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z",
    "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.

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

taskIdstring · mín: 1 · máx: 64Requerido

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

statusCodenumberRequerido

Status code to the request

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

statusMessagestringOpcional

Textual status message

Respuestas

200

updateCardCallback response payload

application/json

500

Internal Server Error

post

/updateCardCallback

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "taskId": "text",
  "statusCode": 1,
  "statusMessage": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z",
    "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.

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

walletCardIdstring · mín: 1 · máx: 64Requerido

The Wallet Card Identifier. Unique for each wallet card.

Respuestas

200

getCardStatus response payload

application/json

statestring · enumOpcionalValores posibles:

500

Internal Server Error

post

/getCardStatus

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "walletCardId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z",
    "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.

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

walletCardAccountIdstring · mín: 1 · máx: 64Requerido

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

Respuestas

200

getCardAccountStatus response payload

application/json

statestring · enumOpcional

The card account state

Valores posibles:

500

Internal Server Error

post

/getCardAccountStatus

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "walletCardAccountId": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "state": "ACTIVE",
  "accountBalance": {
    "balanceAmount": 1,
    "balanceCurrencyCode": "text",
    "balanceDate": "2026-06-17T17:31:51.466Z"
  }
}

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)

Parámetros de encabezado

x-podstring · máx: 128Requerido

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.

Cuerpo

application/json

modestring · enumOpcional

It is needed in the first request only.

Valores posibles:

walletCardIdstring · mín: 1 · máx: 64Requerido

The Wallet Card Identifier. Unique for each wallet card.

Respuestas

200

getCardCommands response payload

application/json

500

Internal Server Error

post

/getCardCommands

HTTPcURLJavaScriptPython

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

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z"
  },
  "mode": "PARK",
  "walletCardId": "text",
  "apduResponses": [
    {
      "rApdu": "text",
      "messageId": "text",
      "messageName": "text"
    }
  ]
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:31:51.466Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "apduCommands": [
    {
      "cApdu": "text",
      "messageId": "text",
      "messageName": "text"
    }
  ]
}