TM Pre-Digitization API (Outbound)

openapi: 3.0.1
info:
  title: TM Pre-Digitization API (Outbound)
  description: 'The TM Pre-Digitization API are used to inform Issuers of services being

    requested by, or on-behalf of, their account holders.<br>     Issuers

    provide information in their responses to guide or inform the Account

    holder’s experience through the Token Requestor.

    '
  version: 1.0.0
  x-artifactId: tm-pre-digitization-api-outbound
  contact:
    email: thorsten.brinkmann@dieboldnixdorf.com
tags:
- name: TM Pre-Digitization API (Outbound)
  description: 'The TM Pre-Digitization API supports the pre-digitization web services provided by the Digitization Service.<br>

    The web services are used to inform Issuers of services being requested by, or on-behalf of, their account holders.<br>

    Issuers provide information in their responses to guide or inform the Account holder’s experience through the Token Reqestor.<br>

    '
  externalDocs:
    description: Find out more
    url: https://dieboldnixdorf.com
externalDocs:
  description: Find out more about Swagger
  url: https://swagger.io
servers:
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/Diebold-Nixdorf/tm-pre-digitization-api-outbound/1.0.0
paths:
  /customerInformation:
    post:
      summary: 'Optional request to get some customer information from the host.

        '
      description: 'An <b><i><font color=''red''>Optional</i></b></font> request to get some customer information from the
        host.

        '
      operationId: custromerInformation
      tags:
      - Activation Methods
      requestBody:
        description: 'Contains the details of the request message.<br>

          <b>Note:</b>The <b>consumerId</b> is optional.

          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInformationRequest'
      responses:
        '200':
          description: Contains the details of the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerInformationResponse'
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '405':
          $ref: '#/components/responses/MethodNotAllowed405'
        '500':
          $ref: '#/components/responses/InternalServerError500'
  /deliverActivationCode:
    post:
      summary: 'DeliverActivationCode is used to request an Activation Code be sent to authenticate the Account holder.

        '
      description: '<b>deliverActivationCode</b> is used to request an Activation Code be sent to authenticate the Account
        holder.<br>

        TM Pre-Digitization API generates an Activation Code and delivers it, along with the chosen Activation Code Distribution
        Method, to the Issuer for transmission to the Account holder.<br>

        The Account holder will then enter the Activation Code into the Mobile Payment App.<br>

        Once an Activation Code has been generated, it will be valid for a limited activation period, after which the code
        will expire.<br>

        Once a code expires, the Issuer can request a new Activation Code via the Customer Service Portal/API, or remotely
        activate the token via the Customer Service Portal/API.<br>

        The Account holder may request the Activation Code again with the same or a different Activation Code Distribution
        Method.  This will trigger another request as long as the activation period has not expired.<br>

        It will not cause the Activation Code to be regenerated nor extend the validity period of the Activation Code.

        '
      operationId: deliverActivationCode
      tags:
      - Activation Methods
      requestBody:
        description: Contains the details of the request message.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliverActivationCodeRequest'
      responses:
        '200':
          description: Contains the details of the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliverActivationCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '405':
          $ref: '#/components/responses/MethodNotAllowed405'
        '500':
          $ref: '#/components/responses/InternalServerError500'
  /digitizationCompleted:
    post:
      summary: 'digitizationCompleted is used to receive notifications that the provisioning and activation of a token for
        a funding account has been completed by the digitization service.

        '
      description: '<b>digitizationCompleted</b> is used to receive notifications that the provisioning and activation of
        a token for a funding account has been completed by the digitization service.

        '
      operationId: notifyServiceActivated
      tags:
      - Activation Methods
      requestBody:
        description: Contains the details of the request message.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DigitizationCompletedRequest'
      responses:
        '200':
          description: Contains the details of the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotifyServiceActivatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '405':
          $ref: '#/components/responses/MethodNotAllowed405'
        '500':
          $ref: '#/components/responses/InternalServerError500'
components:
  responses:
    BadRequest400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MethodNotAllowed405:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict409:
      description: Conflict; The authorization has failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    RequestId:
      type: string
      maxLength: 64
      description: The unique id of the request submitted. Max length - 64
      example: '123456'
    CorrelationId:
      type: string
      maxLength: 14
      description: 'Value linking pre-digitization messages generated during provisioning.<br>

        Max length - 14. Type - String

        '
      example: D98765432104
    FPAN:
      type: string
      maxLength: 128
      description: "A tokenized PAN.  \nMax length - 128. Type - String.\n"
      example: '98765432104676066094325336'
    DPAN:
      type: string
      maxLength: 128
      description: "A tokenized PAN.  \nMax length - 128. Type - String.\n"
      example: '98765432104676066094325336'
    ConsumerId:
      type: string
      maxLength: 88
      description: 'Consumer Identifier provided by the token requestor.<br>

        <b>Note:</b>Not required – Optionally present in AuthorizeService when provided by the wallet provider.<br>

        Max length - 88. Type - String.

        '
      example: '123456'
    DigitalizationDecision:
      type: string
      enum:
      - APPROVED
      - DECLINED
      - REQUIRE_ADDITIONAL_AUTHENTICATION
      description: "The decision that was made by the system or which was recommended by e.g. the Wallet Provider.<br>\nMust\
        \ be one of:<br>\n<ul>\n  <li>APPROVED = Services request was approved, \n  <li>DECLINED = Services request was declined,\
        \ \n  <li>REQUIRE_ADDITIONAL_AUTHENTICATION = Services request requires additional authentication to be approved.</li>\n\
        </ul>\n<br>\nMax length - Not applicable. Type - String.\n"
      example: APPROVED
    ReasonCodes:
      type: array
      description: "The reason the account holder is being authenticated.<br>\nThe reason could impact the generation and\
        \ validation of the code in a number of ways including but not limited to the time period of validity of the code\
        \ and the number of attempts allowed to validate the code.<br>\nNew reason codes can be added at any time and should\
        \ not result in a failure.\n<b>Note:</b>Conditional - Only present for Conset Service\nPossible push methods are:<br>\n\
        <ul>\n  <li>>ADD_CARD: The account holder is being authenticated after adding the card to the token requestor</li>\n\
        \  <li>VERIFY_ACCOUNT: The account holder is being authenticated in order to verify account ownership.</li>\n  <li>OTHER:\
        \ The account holder is being authenticated for a reason not enumerated in this list.</li>\n</ul>\n"
      items:
        type: string
        example: ADD_CARD
    ActivationMethod:
      type: object
      required:
      - type
      - value
      description: The activation methods to be used for this digitization.
      properties:
        type:
          type: string
          enum:
          - SMS_TO_CARDHOLDER
          - EMAIL_TO_CARDHOLDER
          - CALL_TO_CARDHOLDER
          - CARDHOLDER_TO_AUTOMATED_NUMBER
          - CARDHOLDER_TO_CALLCENTER
          - CARDHOLDER_USE_WEB
          - CARDHOLDER_USE_MOBILE_APP
          - null
          description: "Specifies the activation method type. \nMust be one of:<br> \n<ul>\n  <li>SMS_TO_CARDHOLDER = Text\
            \ message to Account holder's mobile phone number. Value will be the Account holder's masked mobile phone number</li>\n\
            \  <li>EMAIL_TO_CARDHOLDER = Email to Account holder's email address. Value will be the Account holder's masked\
            \ email address</li>\n  <li>CALL_TO_CARDHOLDER = Issuer-initiated voice call to Account holder's phone. Value\
            \ will be the Account holder's masked voice call phone number.</li>\n  <li>CARDHOLDER_TO_AUTOMATED_NUMBER = Account\
            \ holder-initiated call to automated call center phone number. Value will be the phone number for the Account\
            \ holder to call</li> \n  <li>CARDHOLDER_TO_CALLCENTER = Account holder-initiated call to manned call center phone\
            \ number. Value will be the phone number for the Account holder to call</li>\n  <li>CARDHOLDER_USE_WEB =  Account\
            \ holder to visit a website. Value will be the website URL</li>\n  <li>CARDHOLDER_USE_MOBILE_APP = Account holder\
            \ to use a specific mobile app to activate token. Value will be the identifier of the mobile app, which is provided\
            \ by the issuer and used by the Account holder</li>\n<ul>\n<br>\n Max length - Not applicable. Type - String.\n"
          example: CARDHOLDER_TO_CALL_AUTOMATED_NUMBER
        value:
          type: string
          maxLength: 64
          description: 'Specifies the activation method value (meaning varies depending on the activation method type).<br>

            Max length - 64. Type - String. Required.

            '
          example: 1-800-BANK-NUMBER
    TokenUniqueNumber:
      type: string
      maxLength: 64
      description: 'A unique reference assigned following the allocation of a token used to identify the token for the duration
        of its lifetime.<br>

        <b>Note:</b> It is required to be always present, even when an error occurs.<br>

        Max length - 64. Type - String.

        '
      example: DWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532
    Error:
      description: "The error property is optional. \nIt is set only if an error has been detected.\n"
      type: object
      required:
      - errorCode
      properties:
        message:
          description: An optional, additional message which describes the error.
          type: string
          maxLength: 256
          example: Internal server error. A database connection could not be established.
        paymentProviderErrorCode:
          description: An error code as outlined in the PI-API documentation.
          type: string
          example: SysErr#765
        errorCode:
          description: An error code as outlined in the PI-API documentation.
          type: string
          example: HOST_CANCEL
        correlationId:
          $ref: '#/components/schemas/CorrelationId'
    MSISDN:
      type: string
      pattern: ^\+(?:[0-9]\x20?){6,14}[0-9]$
      example: +386 1511512564
      description: 'The numbers must start with a plus sign, followed by the country code and national number regarding ITU-T
        E.123 and ITU-T E.164<br>

        Phone numbers cannot contain more than 15 digits. The shortest international phone numbers in use contain seven digits.

        '
    TokenProviderType:
      type: string
      enum:
      - APPLE_PAY
      - GOOGLE_PAY
      - SAMSUNG_PAY
      - GARMIN_PAY
      - XIAOMI_PAY
      - MERCHANT_TOKENIZATION_PROGRAM
      - OTHER
      description: 'The identifier of the Wallet Provider who requested the digitization.<br>

        '
      example: APPLE_PAY
    BankIdentifier:
      type: string
      description: 'The bank identifier of the bank for which the token request is issued.<br>

        The bank identifier is take from the original request.

        '
      example: NLBLJ
    CustomerInformationRequest:
      type: object
      required:
      - requestId
      - correlationId
      - tokenizedPAN
      - consumerId
      - tokenProviderType
      - bankIdentifier
      properties:
        requestId:
          $ref: '#/components/schemas/RequestId'
        correlationId:
          $ref: '#/components/schemas/CorrelationId'
        tokenizedPAN:
          $ref: '#/components/schemas/FPAN'
        consumerId:
          $ref: '#/components/schemas/ConsumerId'
        tokenProviderType:
          $ref: '#/components/schemas/TokenProviderType'
        bankIdentifier:
          $ref: '#/components/schemas/BankIdentifier'
    DeliverActivationCodeRequest:
      type: object
      required:
      - requestId
      - correlationId
      - tokenizedPAN
      - consumerId
      - activationCode
      - expirationDateTime
      - activationMethod
      - tokenProviderType
      - bankIdentifier
      properties:
        requestId:
          $ref: '#/components/schemas/RequestId'
        correlationId:
          $ref: '#/components/schemas/CorrelationId'
        tokenizedPAN:
          $ref: '#/components/schemas/FPAN'
        consumerId:
          $ref: '#/components/schemas/ConsumerId'
        activationCode:
          type: string
          maxLength: 32
          description: 'The Activation Code to be distributed for the digitization.<br>

            <b>Note:</b>Conditional - only present if the payment notwork, e.g. Mastercard generates the activationCode.

            Max length - 32. Type - String.

            '
          example: A1B2C3D4
        expirationDateTime:
          type: string
          format: date-time
          description: 'The DateTime when the Activation Code is no longer valid.<br>

            <b>Note:</b>Conditional - only present if the payment network e.g. Mastercard generates the activationCode.

            Max length - Not applicable. Type - String.

            '
          example: '2016-07-04T12:08:56.123-07:00'
        activationMethod:
          $ref: '#/components/schemas/ActivationMethod'
        reasonCodes:
          $ref: '#/components/schemas/ReasonCodes'
        tokenProviderType:
          $ref: '#/components/schemas/TokenProviderType'
        bankIdentifier:
          $ref: '#/components/schemas/BankIdentifier'
    DigitizationCompletedRequest:
      type: object
      required:
      - requestId
      - correlationId
      - tokenizedPAN
      - tokenUniqueNumber
      - consumerId
      - decision
      - tokenActivatedDateTime
      - tokenProviderType
      - bankIdentifier
      properties:
        requestId:
          $ref: '#/components/schemas/RequestId'
        correlationId:
          $ref: '#/components/schemas/CorrelationId'
        tokenizedPAN:
          $ref: '#/components/schemas/FPAN'
        token:
          $ref: '#/components/schemas/DPAN'
        tokenUniqueNumber:
          $ref: '#/components/schemas/TokenUniqueNumber'
        consumerId:
          $ref: '#/components/schemas/ConsumerId'
        decision:
          $ref: '#/components/schemas/DigitalizationDecision'
        tokenActivatedDateTime:
          type: string
          format: date-time
          description: 'The date, when the token was activated.<br>

            Max length - Not applicable. Type - String.

            '
          example: '2015-07-04T12:09:57.123-07:00'
        tokenProviderType:
          $ref: '#/components/schemas/TokenProviderType'
        bankIdentifier:
          $ref: '#/components/schemas/BankIdentifier'
        sendSMS:
          type: string
          enum:
          - 'true'
          - 'false'
          description: "A flag whether SMS needs to be sent for TCN/TN;<br>\n<ul>\n  <li>true — Indicates that a SMS should\
            \ send.</li>\n  <li>false — Indicates that there is no need to to send a SMS.</li>\n</ul></br>\n"
          example: 'true'
    ResponseId:
      type: string
      maxLength: 64
      description: 'The id of the response sent.<br>

        Required. Max length - 64

        '
      example: '123456'
    CustomerInformationResponse:
      type: object
      required:
      - responseId
      properties:
        responseId:
          $ref: '#/components/schemas/ResponseId'
        accountHolderMobilePhoneNumber:
          $ref: '#/components/schemas/MSISDN'
        automatedCallCenterPhoneNumber:
          $ref: '#/components/schemas/MSISDN'
        mannedCallCenterPhoneNumber:
          $ref: '#/components/schemas/MSISDN'
        accountHolderEmailAddress:
          type: string
          maxLength: 320
          description: 'The email address of the account holder. Max length - 320.<br>

            Max length - 320. Type - String.

            '
          example: abcdef@xyz.com
        webURL:
          type: string
          maxLength: 1024
          description: 'Contains an URL the account holder should visit.

            '
          example: https://xyz.com/verfiycardholder
        mobileApp:
          type: string
          maxLength: 255
          description: 'The mobile app identifier of the account holder.

            '
          example: https://xyz.com/verfiycardholder
    DeliverActivationCodeResponse:
      type: object
      required:
      - responseId
      properties:
        responseId:
          $ref: '#/components/schemas/ResponseId'
    NotifyServiceActivatedResponse:
      type: object
      required:
      - responseId
      properties:
        responseId:
          $ref: '#/components/schemas/ResponseId'