openapi: 3.1.0
info:
  version: '1.0'
  title: D1 Transit Inbound API
servers:
  - url: https://THALES-PROD/d1/transit/api/v1
    description: Prod URL
    x-gitbook-description-html: <p>Prod URL</p>
  - url: https://THALES-STG/d1/transit/api/v1
    description: Staging URL
    x-gitbook-description-html: <p>Staging URL</p>
paths:
  /issuers/{issuerId}/wallets/{walletIndicator}/preparePushProvisioningBundle:
    post:
      summary: Prepare Push Provisioning Bundle
      description: >-
        API used for requesting D1 Transit to prepare a push provisioning bundle
        that is going to be provided by Transit Issuer mobile app to Digital
        Wallet SDK eventually.<br/><br/> This request can be used in 3 different
        cases:<br/>
            1) initial provisioning: in such case, Transit Issuer shall neither provide cardAccountId nor digitalCardId. D1 Transit will create and return these identifiers in the response.<br/>
            2) retry failed provisioning: in case of provisioning failure, Transit Issuer may retry the provisioning, assuming there was no refund/cancellation of customer card account.<br/>
            In such case, both cardAccountId and digitalCardId shall be provided.<br/>
            3) restoring an existing cardAccount: in such case, Transit Issuer shall provide cardAccountId only. D1 Transit will assign new digitalCardId and return it along with cardAccountId in the response.<br/>
      operationId: preparePushProvisioningBundle
      parameters:
        - $ref: '#/components/parameters/issuerId'
        - $ref: '#/components/parameters/walletIndicator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreparePushProvisioningBundleReq'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreparePushProvisioningBundleRes'
        '500':
          $ref: '#/components/responses/error500'
        '503':
          $ref: '#/components/responses/error503'
      servers:
        - url: https://THALES-PROD/d1/transit/api/v1
          description: Prod URL
          x-gitbook-description-html: <p>Prod URL</p>
        - url: https://THALES-STG/d1/transit/api/v1
          description: Staging URL
          x-gitbook-description-html: <p>Staging URL</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >
                      API used for requesting D1 Transit to prepare a push
                      provisioning bundle that is going to be provided by
                      Transit Issuer mobile app to Digital Wallet SDK
                      eventually.


                      This request can be used in 3 different cases:

                      1) initial provisioning: in such case, Transit Issuer
                      shall neither provide cardAccountId nor digitalCardId. D1
                      Transit will create and return these identifiers in the
                      response.

                      2) retry failed provisioning: in case of provisioning
                      failure, Transit Issuer may retry the provisioning,
                      assuming there was no refund/cancellation of customer card
                      account.

                      In such case, both cardAccountId and digitalCardId shall
                      be provided.

                      3) restoring an existing cardAccount: in such case,
                      Transit Issuer shall provide cardAccountId only. D1
                      Transit will assign new digitalCardId and return it along
                      with cardAccountId in the response.
                    marks: []
                key: Z2pvWSEVWTgS
            key: LI4YMsfwVhvj
        key: aAjWfKqqRxSp
      x-gitbook-description-html: >-
        <p>API used for requesting D1 Transit to prepare a push provisioning
        bundle that is going to be provided by Transit Issuer mobile app to
        Digital Wallet SDK eventually.<br><br>This request can be used in 3
        different cases:<br>1) initial provisioning: in such case, Transit
        Issuer shall neither provide cardAccountId nor digitalCardId. D1 Transit
        will create and return these identifiers in the response.<br>2) retry
        failed provisioning: in case of provisioning failure, Transit Issuer may
        retry the provisioning, assuming there was no refund/cancellation of
        customer card account.<br>In such case, both cardAccountId and
        digitalCardId shall be provided.<br>3) restoring an existing
        cardAccount: in such case, Transit Issuer shall provide cardAccountId
        only. D1 Transit will assign new digitalCardId and return it along with
        cardAccountId in the response.<br></p>
  /issuers/{issuerId}/wallets/{walletIndicator}/cancelCardAccount:
    post:
      summary: Cancel Card Account
      description: >-
        API used for cancelling a card account.<br/>Card Account will be removed
        from Digital Wallet systems as well.
      operationId: cancelCardAccount
      parameters:
        - $ref: '#/components/parameters/issuerId'
        - $ref: '#/components/parameters/walletIndicator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelCardAccountReq'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelCardAccountRes'
        '500':
          $ref: '#/components/responses/error500'
        '503':
          $ref: '#/components/responses/error503'
      servers:
        - url: https://THALES-PROD/d1/transit/api/v1
          description: Prod URL
          x-gitbook-description-html: <p>Prod URL</p>
        - url: https://THALES-STG/d1/transit/api/v1
          description: Staging URL
          x-gitbook-description-html: <p>Staging URL</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      API used for cancelling a card account.

                      Card Account will be removed from Digital Wallet systems
                      as well.
                    marks: []
                key: 3bE4pLqFMJXp
            key: af6FiuhTLEQF
        key: dth6NyHXOrfF
      x-gitbook-description-html: >-
        <p>API used for cancelling a card account.<br>Card Account will be
        removed from Digital Wallet systems as well.</p>
  /issuers/{issuerId}/wallets/{walletIndicator}/getCardAccountInfo:
    post:
      summary: Get Card Account Info
      description: API used for getting card account information.
      operationId: getCardAccountInfo
      parameters:
        - $ref: '#/components/parameters/issuerId'
        - $ref: '#/components/parameters/walletIndicator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCardAccountInfoReq'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCardAccountInfoRes'
        '500':
          $ref: '#/components/responses/error500'
        '503':
          $ref: '#/components/responses/error503'
      servers:
        - url: https://THALES-PROD/d1/transit/api/v1
          description: Prod URL
          x-gitbook-description-html: <p>Prod URL</p>
        - url: https://THALES-STG/d1/transit/api/v1
          description: Staging URL
          x-gitbook-description-html: <p>Staging URL</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: API used for getting card account information.
                    marks: []
                key: yau1CHTpFv8P
            key: bibR9H2kcAja
        key: PLolO1dTBJNG
      x-gitbook-description-html: <p>API used for getting card account information.</p>
  /issuers/{issuerId}/wallets/{walletIndicator}/manageDigitalCard:
    post:
      summary: Manage Digital Card
      description: >-
        API used for managing the state of a digital card provisioned into a
        device.
      operationId: manageDigitalCard
      parameters:
        - $ref: '#/components/parameters/issuerId'
        - $ref: '#/components/parameters/walletIndicator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManageDigitalCardReq'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManageDigitalCardRes'
        '500':
          $ref: '#/components/responses/error500'
        '503':
          $ref: '#/components/responses/error503'
      servers:
        - url: https://THALES-PROD/d1/transit/api/v1
          description: Prod URL
          x-gitbook-description-html: <p>Prod URL</p>
        - url: https://THALES-STG/d1/transit/api/v1
          description: Staging URL
          x-gitbook-description-html: <p>Staging URL</p>
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 9
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      API used for managing the state of a digital card
                      provisioned into a device.
                    marks: []
                key: kRLTtfWgWoHv
            key: v9RE4ai5ytDc
        key: NRFe9EYKChTl
      x-gitbook-description-html: >-
        <p>API used for managing the state of a digital card provisioned into a
        device.</p>
components:
  parameters:
    issuerId:
      name: issuerId
      in: path
      description: Issuer unique identifier. Assigned by Thales during onboarding.
      required: true
      schema:
        type: string
        maxLength: 10
      x-gitbook-description-html: <p>Issuer unique identifier. Assigned by Thales during onboarding.</p>
    walletIndicator:
      name: walletIndicator
      in: path
      description: |-
        Indicates which digital wallet is involved in the use case.
        |Value|Description|
        |---|---|
        |1|Apple|
        |2|Google|
        |3|Samsung|        
      required: true
      schema:
        type: number
      x-gitbook-description-html: >-
        <p>Indicates which digital wallet is involved in the use case.</p>






















        <table><thead><tr><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td>Apple</td></tr><tr><td>2</td><td>Google</td></tr><tr><td>3</td><td>Samsung</td></tr></tbody></table>
  responses:
    error500:
      description: >
        An unexpected error occurred while processing the request.<br/>

        The request cannot be retried.<br/>

        Only used in cases where it's not be possible to provide more
        information about what went wrong with the request (i.e. return <b>HTTP
        200</b> with '<b>responseContext</b>').
      x-gitbook-description-html: >-
        <p>An unexpected error occurred while processing the request.<br>

        The request cannot be retried.<br>

        Only used in cases where it's not be possible to provide more
        information about what went wrong with the request (i.e. return <b>HTTP
        200</b> with '<b>responseContext</b>').</p>
    error503:
      description: |
        Indicates that the system is unavailable.<br/>
        The request can be retried.
      x-gitbook-description-html: |-
        <p>Indicates that the system is unavailable.<br>
        The request can be retried.</p>
  schemas:
    PreparePushProvisioningBundleReq:
      type: object
      properties:
        requestContext:
          $ref: '#/components/schemas/requestContext'
        cardAccountId:
          $ref: '#/components/schemas/cardAccountId'
        digitalCardId:
          $ref: '#/components/schemas/digitalCardId'
        pushDetails:
          description: >-
            pushDetails shall be consistent with the 'wallet indicator'
            parameter.<br/>

            I.e. ApplePushDetails shall be provided when 'wallet indicator' = 1,
            GooglePushDetails shall be provided when 'wallet indicator' = 2
          oneOf:
            - $ref: '#/components/schemas/ApplePushDetails'
            - $ref: '#/components/schemas/GooglePushDetails'
          x-gitbook-description-html: >-
            <p>pushDetails shall be consistent with the 'wallet indicator'
            parameter.<br>

            I.e. ApplePushDetails shall be provided when 'wallet indicator' = 1,
            GooglePushDetails shall be provided when 'wallet indicator' = 2</p>
      required:
        - requestContext
        - pushDetails
    requestContext:
      type: object
      properties:
        requestId:
          type: string
          description: Request unique identifier. Should be different for every retry.
          maxLength: 64
          examples:
            - 493f7686-93a0-494a-a44f-867fcd10ce22
          x-gitbook-description-html: >-
            <p>Request unique identifier. Should be different for every
            retry.</p>
        correlationId:
          type: string
          description: >-
            Random identifier which can be used to correlate the different API
            calls done as part of a usecase.

            There is no strong guarantee of the uniqueness of this identifier,
            so it should not be used for purposes other than logging and
            troubleshooting.
          maxLength: 64
          examples:
            - bfd8450f-a605-4427-9714-1d620f14dda1
          x-gitbook-description-html: >-
            <p>Random identifier which can be used to correlate the different
            API calls done as part of a usecase.

            There is no strong guarantee of the uniqueness of this identifier,
            so it should not be used for purposes other than logging and
            troubleshooting.</p>
      required:
        - requestId
        - correlationId
    cardAccountId:
      type: string
      description: Card account unique identifier
      maxLength: 64
      examples:
        - FAPLSW8D8AC610566D4EF09C22186B2A5ED793
      x-gitbook-description-html: <p>Card account unique identifier</p>
    digitalCardId:
      type: string
      description: Digital card unique identifier
      maxLength: 64
      examples:
        - DGGLSW8D8AC610566D4EF09C22186B2A5ED756
      x-gitbook-description-html: <p>Digital card unique identifier</p>
    ApplePushDetails:
      type: object
      title: ApplePushDetails
      properties:
        certificates:
          type: array
          description: >
            Leaf and intermediate certificates provided by Apple's
            servers.<br/>They're retrieved by the transit issuer app using <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassviewcontroller">PKAddPaymentPassViewController</a>
          items:
            type: string
          x-gitbook-description-html: >-
            <p>Leaf and intermediate certificates provided by Apple's
            servers.<br>They're retrieved by the transit issuer app using <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassviewcontroller">PKAddPaymentPassViewController</a></p>
        nonce:
          type: string
          description: >
            A one-time nonce value generated by Apple's servers.<br/>It's
            retrieved by the transit issuer app using <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassviewcontroller">PKAddPaymentPassViewController</a>
          x-gitbook-description-html: >-
            <p>A one-time nonce value generated by Apple's servers.<br>It's
            retrieved by the transit issuer app using <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassviewcontroller">PKAddPaymentPassViewController</a></p>
        nonceSignature:
          type: string
          description: >
            A device-specific signature for the nonce.<br/>It's retrieved by the
            transit issuer app using <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassviewcontroller">PKAddPaymentPassViewController</a>
          x-gitbook-description-html: >-
            <p>A device-specific signature for the nonce.<br>It's retrieved by
            the transit issuer app using <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassviewcontroller">PKAddPaymentPassViewController</a></p>
      required:
        - certificates
        - nonce
        - nonceSignature
    GooglePushDetails:
      type: object
      title: GooglePushDetails
      properties:
        walletId:
          type: string
          description: >
            Identifier of the active Google Wallet.<br/>It's retrieved by the
            transit issuer app using <a
            href="https://developers.google.com/pay/issuers/apis/push-provisioning/android/reading-wallet#getactivewalletid">getActiveWalletId</a>
            TapAndPay function.
          x-gitbook-description-html: >-
            <p>Identifier of the active Google Wallet.<br>It's retrieved by the
            transit issuer app using <a
            href="https://developers.google.com/pay/issuers/apis/push-provisioning/android/reading-wallet#getactivewalletid">getActiveWalletId</a>
            TapAndPay function.</p>
      required:
        - walletId
    PreparePushProvisioningBundleRes:
      type: object
      properties:
        responseContext:
          $ref: '#/components/schemas/responseContext'
        cardAccountId:
          $ref: '#/components/schemas/cardAccountId'
          description: |
            Unique identifier of an account.<br/>Not provided in case of error.
          x-gitbook-description-html: >-
            <p>Unique identifier of an account.<br>Not provided in case of
            error.</p>
        digitalCardId:
          $ref: '#/components/schemas/digitalCardId'
          description: >
            Unique identifier of a digital card.<br/>Not provided in case of
            error.
          x-gitbook-description-html: >-
            <p>Unique identifier of a digital card.<br>Not provided in case of
            error.</p>
        pushProvisioningBundle:
          type: string
          description: >
            Bundle generated as per Digital Wallet format specified in the

            request.<br/>It shall be used by the transit issuer app to trigger

            the provisioning.



            **Apple format**<br/>


            This is the string representation of JSON object defined as below:


            |Parameter name|Type|Description|

            |-------|-------|-------|

            |activationData|string|See
            https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/activationdata|

            |encryptedPassData|string|See
            https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/encryptedpassdata|

            |ephemeralPublicKey|string|See
            https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/ephemeralpublickey|



            **Google format**<br/>


            This is the OpaquePaymentCard (OPC) as described in

            https://developers.google.com/pay/issuers/apis/push-provisioning/android/wallet-operations



            Not provided in case of error.                   
          x-gitbook-description-html: >-
            <p>Bundle generated as per Digital Wallet format specified in the

            request.<br>It shall be used by the transit issuer app to trigger

            the provisioning.</p>

            <p><strong>Apple format</strong><br></p>

            <p>This is the string representation of JSON object defined as
            below:</p>


























            <table><thead><tr><th>Parameter
            name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>activationData</td><td>string</td><td>See
            <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/activationdata">https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/activationdata</a></td></tr><tr><td>encryptedPassData</td><td>string</td><td>See
            <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/encryptedpassdata">https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/encryptedpassdata</a></td></tr><tr><td>ephemeralPublicKey</td><td>string</td><td>See
            <a
            href="https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/ephemeralpublickey">https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/ephemeralpublickey</a></td></tr></tbody></table>

            <p><strong>Google format</strong><br></p>

            <p>This is the OpaquePaymentCard (OPC) as described in

            <a
            href="https://developers.google.com/pay/issuers/apis/push-provisioning/android/wallet-operations">https://developers.google.com/pay/issuers/apis/push-provisioning/android/wallet-operations</a></p>

            <p>Not provided in case of error.</p>
      required:
        - responseContext
    responseContext:
      type: object
      description: >
        Should be used for most of responses, even if the request processing was
        not successful.

        If there was an issue encountered during request processing, the
        statusCode and statusMessage are used to give more details about what
        has gone wrong.
      properties:
        requestId:
          type: string
          description: requestId value from the corresponding request.
          maxLength: 64
          examples:
            - a762c0a1-2ae7-42b1-a4d8-8d8ba09bdf30
          x-gitbook-description-html: <p>requestId value from the corresponding request.</p>
        statusCode:
          type: number
          examples:
            - 0
        statusMessage:
          type: string
          examples:
            - OK
      required:
        - requestId
        - statusCode
      x-gitbook-description-html: >-
        <p>Should be used for most of responses, even if the request processing
        was not successful.

        If there was an issue encountered during request processing, the
        statusCode and statusMessage are used to give more details about what
        has gone wrong.</p>
    CancelCardAccountReq:
      type: object
      properties:
        requestContext:
          $ref: '#/components/schemas/requestContext'
        cardAccountId:
          $ref: '#/components/schemas/cardAccountId'
      required:
        - requestContext
        - cardAccountId
    CancelCardAccountRes:
      type: object
      properties:
        responseContext:
          $ref: '#/components/schemas/responseContext'
      required:
        - responseContext
    GetCardAccountInfoReq:
      type: object
      properties:
        requestContext:
          $ref: '#/components/schemas/requestContext'
        cardAccountId:
          $ref: '#/components/schemas/cardAccountId'
      required:
        - requestContext
        - cardAccountId
    GetCardAccountInfoRes:
      type: object
      properties:
        responseContext:
          $ref: '#/components/schemas/responseContext'
        cardAccountState:
          $ref: '#/components/schemas/cardAccountState'
        userId:
          $ref: '#/components/schemas/userId'
        digitalCards:
          type: array
          description: list of digital cards linked to the card account.
          items:
            type: object
            properties:
              digitalCardId:
                $ref: '#/components/schemas/digitalCardId'
              digitalCardState:
                $ref: '#/components/schemas/digitalCardState'
              walletId:
                $ref: '#/components/schemas/walletId'
              deviceType:
                $ref: '#/components/schemas/deviceType'
              csn:
                $ref: '#/components/schemas/csn'
            required:
              - digitalCardId
              - digitalCardState
              - walletId
          x-gitbook-description-html: <p>list of digital cards linked to the card account.</p>
      required:
        - responseContext
    cardAccountState:
      type: string
      enum:
        - active
        - cancelled
        - parked
      description: Card account state
      x-gitbook-description-html: <p>Card account state</p>
    userId:
      type: string
      description: User unique identifier
      maxLength: 64
      examples:
        - sSHfawfGsHUQjg8zaOHnPPgso5TF
      x-gitbook-description-html: <p>User unique identifier</p>
    digitalCardState:
      type: string
      enum:
        - created
        - failed_provisioning
        - active
        - deleted
        - unlinked
        - suspended_wallet
        - suspended_issuer
      description: Digital card state
      x-gitbook-description-html: <p>Digital card state</p>
    csn:
      type: string
      description: Calypso serial number.<br/>Applicable for Calypso technology only.
      maxLength: 16
    walletId:
      type: string
      description: >-
        Wallet unique identifier.<br/>Corresponds to unique device identifier
        for Apple and Samsung.<br/>Corresponds to unique identifier assigned for
        a given user and device for Google.
      maxLength: 64
      examples:
        - 9i+KsSHjySa7Nxyzpvp6V/mL/fhwwZ7H/NEE9XCGjO6zzKiNnimDDAVHxOFa0jKF
      x-gitbook-description-html: >-
        <p>Wallet unique identifier.<br>Corresponds to unique device identifier
        for Apple and Samsung.<br>Corresponds to unique identifier assigned for
        a given user and device for Google.</p>
    deviceType:
      type: number
      description: |
        Device type.
        |value|description|
        |-------|-------|
        |1|Phone|
        |2|Tablet|
        |3|Watch|
        |4-99|RFU|
      x-gitbook-description-html: >-
        <p>Device type.</p>


























        <table><thead><tr><th>value</th><th>description</th></tr></thead><tbody><tr><td>1</td><td>Phone</td></tr><tr><td>2</td><td>Tablet</td></tr><tr><td>3</td><td>Watch</td></tr><tr><td>4-99</td><td>RFU</td></tr></tbody></table>
    ManageDigitalCardReq:
      type: object
      properties:
        requestContext:
          $ref: '#/components/schemas/requestContext'
        digitalCardId:
          $ref: '#/components/schemas/digitalCardId'
        cardAccountId:
          $ref: '#/components/schemas/cardAccountId'
        action:
          type: string
          enum:
            - unlink
            - suspend
            - resume
      required:
        - requestContext
        - digitalCardId
        - cardAccountId
        - action
    ManageDigitalCardRes:
      type: object
      properties:
        responseContext:
          $ref: '#/components/schemas/responseContext'
      required:
        - responseContext
