openapi: 3.0.0
info:
  contact:
    name: ''
  title: D1 Services API - BankBackend API
  version: '1.0'
  description: D1 Services API - BankBackend API
servers:
  - url: https://YOUR_DOMAIN_NAME
    description: Production server
security:
  - bearerAuth: []
paths:
  /banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}?cardId=<cardId>:
    get:
      description: |-
        This request is used by the D1 backend to request the details of an end user (consumer) from the issuer backend.<br/>

        <i>If the end user information is associated with the card, it is possible to activate "cardId" query parameter via an onboarding flag.</i>
      responses:
        '200':
          description: All needed information related to the requested end user (consumer).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consumerInfo'
        '403':
          description: Forbidden (Invalid state)
        '404':
          description: End user (consumer) was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      summary: Get Consumer Information
      operationId: getConsumerInfo
      parameters:
        - $ref: '#/components/parameters/issuer-id-path'
        - $ref: '#/components/parameters/consumer-id-path'
        - $ref: '#/components/parameters/x-correlation-id'
        - schema:
            $ref: '#/components/schemas/cardId'
            example: 'cardId=crd_h2otddwm5uwujlye3qyxmjkpha '
          in: query
          name: cardId
  /banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}/otp:
    parameters:
      - $ref: '#/components/parameters/issuer-id-path'
      - $ref: '#/components/parameters/consumer-id-path'
      - $ref: '#/components/parameters/x-correlation-id'
    post:
      summary: Deliver OTP
      operationId: deliver-otp
      responses:
        '204':
          description: No Content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authorization missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Action forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      description: |-
        This request is used by D1 during the tokenization flow for a card in case it is required to send an OTP to the end user (consumer) "consumerId".

        The parameter 'threeDSDetails' is available in the scenario :
          * 3DS Authentication
        <!-- theme: info -->
        >### Note 
        > This is applicable only if the issuer decides to rely on its own messaging system to send messages to their customers and not on the D1 platform.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                otp:
                  type: object
                  description: The OTP value
                  required:
                    - value
                    - reason
                  properties:
                    value:
                      type: string
                      minLength: 1
                      maxLength: 15
                    expirationDate:
                      type: string
                      description: |-
                        The expiration time for OTP.</br>
                        Format shall be expressed in ISO 8601 extended format: <b>YYYY-MM-DDThh:mm:ss[.SSS]Z</b></br>
                        where [.SSS] is optional and can be from 1 to 3 digits.</br>
                        Value will be in GMT.
                      minLength: 4
                      maxLength: 32
                    reason:
                      type: string
                      enum:
                        - CARD-DIGITIZATION
                        - DEVICE-BINDING
                        - CARDHOLDER-VERIFICATION
                        - 3DS-AUTHENTICATION
                deliveryChannel:
                  type: string
                  enum:
                    - SMS
                    - EMAIL
                  description: The channel on which the end user has decided to receive the OTP.
                digitalCardRequestor:
                  $ref: '#/components/schemas/digitalCardRequestorInformation'
                deviceInformation:
                  $ref: '#/components/schemas/deviceInformationForOTP'
                panSuffix:
                  type: string
                  minLength: 4
                  maxLength: 4
                  description: Last 4 digits of the PAN of the card to be tokenized (digitized)
                threeDSDetails:
                  type: object
                  properties:
                    acsTransactionId:
                      description: The ACS transaction identifier.
                      type: string
                    purchase:
                      description: The purchase details of the payment 3DS Authentication.<br>In case of non-payment authentication, 'amount' and 'currencyCode' are not present.
                      type: object
                      properties:
                        merchantName:
                          description: The merchant name.
                          type: string
                        amount:
                          description: The nominal transaction amount value. Value without the decimal operator. Use the currency exponent to display amount with decimal. For example, a amount of 789.99€ Euro is sent as 78999.
                          type: string
                        currencyCode:
                          description: The transaction currency code. Currency code in ISO 4217 numeric code format.
                          type: string
              required:
                - otp
                - deliveryChannel
                - panSuffix
  /banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}/authentication:
    parameters:
      - $ref: '#/components/parameters/issuer-id-path'
      - $ref: '#/components/parameters/consumer-id-path'
      - $ref: '#/components/parameters/x-correlation-id'
    post:
      summary: Authenticate
      operationId: authenticate-consumer
      description: This request is sent by D1 to request an end user authentication.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - authenticationId
                - operation
              properties:
                authenticationId:
                  type: string
                  description: The authentication request identifier. For 3DS, the value is the same as the 'acsTransactionId'.
                operation:
                  type: string
                  description: The operation type.
                  enum:
                    - 3DS_CHALLENGE_OOB_ISSUER
                details:
                  oneOf:
                    - title: 3DS_CHALLENGE_OOB_ISSUER operation
                      description: Details information that depends on the operation.
                      properties:
                        cardId:
                          $ref: '#/components/schemas/cardId'
                        panSuffix:
                          type: string
                          minLength: 4
                          maxLength: 4
                          description: Last 4 digits of the card PAN which relates to this deliverOTP operation.
                        acsTransactionId:
                          description: The ACS transaction identifier.
                          type: string
                        purchase:
                          description: The purchase details of the payment 3DS Authentication.<br>In case of non-payment authentication, 'amount' and 'currencyCode' are not present.
                          type: object
                          properties:
                            merchantName:
                              description: The merchant name.
                              type: string
                            amount:
                              description: The nominal transaction amount value. Value without the decimal operator. Use the currency exponent to display amount with decimal. For example, a amount of 789.99€ Euro is sent as 78999.
                              type: string
                            currencyCode:
                              description: The transaction currency code. Currency code in ISO 4217 alpha code format.
                              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - authenticationStatus
                properties:
                  authenticationStatus:
                    type: string
                    description: Status of the operation
                    enum:
                      - AUTHENTICATED
                      - PENDING
                      - NO_AUTHENTICATOR
        '401':
          description: Authorization missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Action forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}/authentication/{authenticationId}:
    parameters:
      - $ref: '#/components/parameters/issuer-id-path'
      - $ref: '#/components/parameters/consumer-id-path'
      - $ref: '#/components/parameters/x-correlation-id'
      - schema:
          type: string
        description: The authentication identifier.
        in: path
        name: authenticationId
        required: true
    get:
      description: Polling request to get the authentication result.
      summary: Get Authentication Result
      operationId: getAuthenticationResult
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - authenticationStatus
                properties:
                  authenticationStatus:
                    type: string
                    description: Status of the operation
                    enum:
                      - AUTHENTICATED
                      - PENDING
                      - AUTHENTICATION_FAILED
                      - TECHNICAL_ERROR
                  reason:
                    type: string
                    minLength: 1
                    maxLength: 64
                    description: The reason of the technical error. Human readable text without personal or sensitive data.
        '403':
          description: Forbidden (Invalid state)
        '404':
          description: End user (consumer) was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /banking/d1/v1/issuers/{issuerId}/consumers/{consumerId}/notifications:
    parameters:
      - $ref: '#/components/parameters/issuer-id-path'
      - $ref: '#/components/parameters/consumer-id-path'
      - $ref: '#/components/parameters/x-correlation-id-output'
    post:
      summary: Notify Consumer Operation (V1)
      operationId: notify-consumer-operation
      description: This request is used by D1 to notify the issuer backend about operations done on a consumer.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/consumerOperationNotification'
      responses:
        '204':
          description: Successful
        '400':
          description: Bad Request, Invalid request URI or header, or unsupported nonstandard parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: The provided Authorization header is missing or invalid
        '404':
          description: Resource not found. Unknown issuerId or consumerId or accountId or cardId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /notifications/d1/v2/issuers/{issuerId}/consumers:
    parameters:
      - $ref: '#/components/parameters/issuer-id-path'
      - $ref: '#/components/parameters/x-correlation-id-output'
    post:
      summary: Notify Consumer Operations (V2)
      operationId: notify-consumer-operations
      description: This request is used by D1 to notify the issuer backend about operations done on a consumer.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                operations:
                  type: array
                  items:
                    $ref: '#/components/schemas/consumerOperations'
      responses:
        '204':
          description: Successful
        '400':
          description: Bad Request, Invalid request URI or header, or unsupported nonstandard parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: The provided Authorization header is missing or invalid
        '404':
          description: Resource not found. Unknown issuerId or consumerId or accountId or cardId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    consumerOperations:
      title: Operation
      type: object
      required:
        - operationId
        - operation
        - status
        - startTime
        - consumerId
      properties:
        operationId:
          $ref: '#/components/schemas/operationId'
        operation:
          type: string
          enum:
            - CLICK_TO_PAY_UPDATE
            - CLICK_TO_PAY_OPTOUT
          description: Consumer operation
          example: CLICK_TO_PAY_UPDATE
        status:
          type: string
          enum:
            - PENDING
            - SUCCESSFUL
            - FAILED
          description: The operation status
          example: SUCCESSFUL
        startTime:
          type: string
          description: Time of the operation
          minLength: 1
          maxLength: 64
          example: '2022-06-16T06:28:02.492Z'
        endTime:
          type: string
          description: End time of the operation
          minLength: 1
          maxLength: 64
          example: '2022-06-16T09:28:12.492Z'
        consumerId:
          $ref: '#/components/schemas/consumerId'
        details:
          description: Optional object to get more details on the operation it self. The object definition will depend on the type of operation.
          oneOf:
            - $ref: '#/components/schemas/EmptyDetails'
        errorCode:
          type: string
          description: The type of the error
          example: FIELD_INVALID_FORMAT
        error:
          type: string
          description: Provide more error details if possible.<br/>For example name of the field with invalid format.
          example: consumerId
    EmptyDetails:
      type: object
      example: {}
    consumerOperationNotification:
      title: Consumer Operation
      type: object
      description: Operation details related to a specific operationId
      properties:
        operationId:
          $ref: '#/components/schemas/operationId'
        operation:
          type: string
          description: The operation type.
          enum:
            - ENROLL_AUTHN
        status:
          $ref: '#/components/schemas/operationStatusSuccessfulFailed'
        startTime:
          $ref: '#/components/schemas/operationStartTime'
        endTime:
          $ref: '#/components/schemas/operationEndTime'
        requestorType:
          type: string
          enum:
            - USER
        requestorId:
          type: string
          description: The consumerId of the end user.
        details:
          type: object
          oneOf:
            - title: ENROLL_AUTHN operation
              properties:
                appInstanceId:
                  $ref: '#/components/schemas/appInstanceId'
                authnType:
                  $ref: '#/components/schemas/authnType'
        error:
          $ref: '#/components/schemas/operationError'
      required:
        - operationId
        - operation
        - status
        - startTime
        - requestorId
        - requestorType
    consumerInfo:
      type: object
      title: ConsumerInfo
      description: The following objects represent the personal information of the end user (consumer).
      properties:
        language:
          type: string
          description: 'Language of the end user (consumer). Based on ISO format for language (ISO 639–1) and an alpha-2 country code (ISO 3166–1 alpha-2). The language must be lowercase, and the country must be uppercase ideally. The language and country should be separated using a minus character "-".<br/>**Note**: This field is mandatory for Click to Pay.'
          minLength: 5
          maxLength: 5
          pattern: ^[a-z]{2}-[a-zA-Z]{2}$
          example: en-US
        firstName:
          type: string
          description: 'First name of the end user (consumer).<br/>**Note**: This field is mandatory for Click to Pay.'
          minLength: 1
          maxLength: 128
          pattern: ^[\p{L}\p{N}\u0600-\u06FF ,.'_#;:\/-]{1,128}$
          example: John
        middleName:
          type: string
          description: Middle name of the end user (consumer).
          minLength: 1
          maxLength: 128
          pattern: ^[\p{L}\p{N}\u0600-\u06FF ,.'_#;:\/-]{1,128}$
          example: John
        lastName:
          type: string
          description: 'Last name of the end user (consumer).<br/>**Note**: This field is mandatory for Click to Pay.'
          minLength: 1
          maxLength: 128
          pattern: ^[\p{L}\p{N}\u0600-\u06FF ,.'_#;:\/-]{1,128}$
          example: Smith
        dateOfBirth:
          type: string
          description: Date of Birth.
          pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[0-1])$
          example: '1990-01-25'
        title:
          type: string
          description: Title of the end user (consumer).
          minLength: 1
          maxLength: 40
          pattern: ^[\p{L}\p{N}\u0600-\u06FF ,.'_#;:\/-]{1,40}$
          example: Mr.
        email:
          type: string
          description: 'Email of the end user (consumer).<br/>**Note**: This field is mandatory for Click to Pay (Mastercard).'
          pattern: ^[a-zA-Z0-9_+&*-]+(?:\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,15}$
          example: john.smith@dummymail.com
        mobilePhoneNumber:
          type: object
          description: 'Phonenumber of the end user (consumer).<br/>**Note**: This field is mandatory for Click to Pay.'
          properties:
            countryCode:
              type: string
              description: International country code for "phoneNumber".
              minLength: 1
              maxLength: 10
              pattern: ^\+[0-9]{1,10}$
              example: '+420'
            phoneNumber:
              type: string
              description: Phone number.
              minLength: 1
              maxLength: 14
              pattern: ^[0-9]{1,14}$
              example: '777222333'
          required:
            - countryCode
            - phoneNumber
        residencyAddress:
          type: object
          description: 'Residency address.<br/>**Note**: This field is mandatory for Click to Pay.'
          properties:
            line1:
              type: string
              description: First line of the address.
              minLength: 1
              maxLength: 256
              pattern: ^[\p{L}\p{N}\u0600-\u06FF ,.'_#;:\/-]{1,256}$
              example: Street#1
            line2:
              type: string
              description: Second line of the address.
              minLength: 1
              maxLength: 256
              pattern: ^[\p{L}\p{N}\u0600-\u06FF ,.'_#;:\/-]{1,256}$
              example: 'Street #2'
            city:
              type: string
              description: City.
              minLength: 1
              maxLength: 128
              pattern: ^[\p{L}\p{N}\u0600-\u06FF ,.'_#;:\/-]{1,128}$
              example: Prague
            state:
              type: string
              description: State.
              minLength: 1
              maxLength: 128
              pattern: ^[\p{L}\p{N}\u0600-\u06FF ,.'_#;:\/-]{1,128}$
              example: CZ
            zipCode:
              type: string
              description: Zip Code.
              minLength: 1
              maxLength: 10
              pattern: ^[0-9a-zA-Z ]{1,10}$
              example: 140 00
            countryCode:
              type: string
              description: 'Country code. Based on ISO 3166-1 alpha-2 format.<br/>**Note**: This field is mandatory for Click to Pay.'
              minLength: 2
              maxLength: 2
              pattern: ^[A-Z]{2}$
              example: CZ
          required:
            - line1
            - zipCode
            - countryCode
      required:
        - firstName
        - lastName
    error:
      title: error
      type: object
      x-examples:
        Example 1:
          error: This is an error message
      description: An error occured
      properties:
        error:
          type: string
          description: Detailed description of the error occured.
    issuerId:
      maxLength: 10
      minLength: 10
      type: string
    consumerId:
      type: string
      description: 'Unique identifier of the consumer. '
      minLength: 1
      maxLength: 64
      pattern: ^[A-Za-z0-9_-]{1,64}$
    cardId:
      type: string
      description: Unique identifier of the card.
      minLength: 1
      maxLength: 48
      pattern: ^[A-Za-z0-9_-]{1,48}$
    digitalCardRequestorInformation:
      title: digitalCardRequestorInformation
      additionalProperties: false
      type: object
      description: Provides details about the digital card requestor.
      properties:
        id:
          type: string
          description: Digital Card requestor identifier. This is provided by the TSP itself.
          minLength: 11
          maxLength: 11
        walletId:
          type: string
          description: MasterCard ONLY. Wallet Application identifier
          maxLength: 32
        name:
          type: string
          maxLength: 256
          description: Wallet or Merchant human readable name
        tspId:
          type: string
          maxLength: 11
          minLength: 11
          description: VISA only. Identifiers of the couple Token Requestor - Token Service Provider
        originalDigitalCardRequestorId:
          type: string
          description: Applies only to VISA in case of token for token provisioning
          minLength: 11
          maxLength: 11
    deviceInformationForOTP:
      title: deviceInformationForOTP
      additionalProperties: false
      type: object
      description: |-
        Provides details about the device that has been used to trigger the request.

        Data availability dependes on the requestor.
      properties:
        digitalCardStorageType:
          type: string
          maxLength: 32
          description: |-
            Type of the token sorage location. Following values are possible:
            - HCE
            - SPAY_PHONE
            - SPAY_TABLET
            - SPAY_WATCH
            - SPAY_TV
            - IPHONE
            - IWATCH
            - IPAD
            - MAC_BOOK
            - ANDROID_PHONE
            - ANDROID_TABLET
            - ANDROID_WATCH
            - MOBILE_PHONE
            - TABLET
            - WATCH
            - MOBILE_PHONE_OR_TABLET
            - BRACELET
            - UNKNOWN
        phoneNumber:
          type: string
          description: Device phone number
          minLength: 1
          maxLength: 20
        deviceName:
          type: string
          maxLength: 128
          description: Device name set by the consumer
    operationId:
      type: string
      description: Unique identifier of the operation
      minLength: 1
      maxLength: 64
      pattern: ^[A-Za-z0-9_-]{1,64}$
    operationStatusSuccessfulFailed:
      type: string
      description: Status of the operation
      enum:
        - SUCCESSFUL
        - FAILED
    operationStartTime:
      type: string
      title: Operation Start Time
      description: |-
        The time the request has been processed.
        Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD
      minLength: 1
      maxLength: 64
      example: '2022-06-16T06:28:02.492Z'
    operationEndTime:
      type: string
      title: Operation End Time
      description: |-
        The time the operation has been completed.
        Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD
        note: This is an optional field and might not be returned for synchronous operations.
      minLength: 1
      maxLength: 64
      example: '2022-06-16T06:28:32.492Z'
    appInstanceId:
      description: Unique identifier of the issuer application instance.
      type: string
    authnType:
      type: string
      enum:
        - BIOMETRIC
        - PLATFORM
    operationError:
      type: string
      description: Human readable string representing the error, only present in case of operation failure
  securitySchemes:
    bearerAuth:
      type: http
      description: A JWT generated by the [Get Authorization Token API](oauth2-api).<br/>The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.
      scheme: bearer
      bearerFormat: JWT
  responses: {}
  parameters:
    issuer-id-path:
      description: The id of the issuer
      in: path
      name: issuerId
      required: true
      schema:
        $ref: '#/components/schemas/issuerId'
    consumer-id-path:
      description: The id of the consumer
      in: path
      name: consumerId
      required: true
      schema:
        $ref: '#/components/schemas/consumerId'
    x-correlation-id:
      description: |-
        Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

        **Warning:** This identifier should not be derived from sensitive personal data, as its value will be logged in clear.

        There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.
      in: header
      name: x-correlation-id
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]{1,64}$
    x-correlation-id-output:
      description: |-
        Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

        There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.
      in: header
      name: x-correlation-id
      schema:
        type: string
