Diebold Nixdorf Activation Methods API

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

    requested by, or on-behalf of, their account holders.

    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
servers:
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/Diebold-Nixdorf/tm-pre-digitization-api-outbound/1.0.0
tags:
- name: Activation Methods
paths:
  /customerInformation:
    post:
      summary: Optional request to get some customer information from the host
      description: An Optional 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…
      description: 'deliverActivationCode is used to request an Activation Code be sent to authenticate the Account holder.


        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.


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


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


        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.


        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.


        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…
      description: 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.
      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:
  schemas:
    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
    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
    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'
    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
    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
    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'
    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'
    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'
    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
    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
    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
    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.

        '
    NotifyServiceActivatedResponse:
      type: object
      required:
      - responseId
      properties:
        responseId:
          $ref: '#/components/schemas/ResponseId'
    RequestId:
      type: string
      maxLength: 64
      description: The unique id of the request submitted. Max length - 64
      example: '123456'
    DPAN:
      type: string
      maxLength: 128
      description: "A tokenized PAN.  \nMax length - 128. Type - String.\n"
      example: '98765432104676066094325336'
    DeliverActivationCodeResponse:
      type: object
      required:
      - responseId
      properties:
        responseId:
          $ref: '#/components/schemas/ResponseId'
    ResponseId:
      type: string
      maxLength: 64
      description: 'The id of the response sent.<br>

        Required. Max length - 64

        '
      example: '123456'
    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'
    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'
  responses:
    MethodNotAllowed405:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
externalDocs:
  description: Find out more about Swagger
  url: https://swagger.io