openapi: 3.1.0
info:
  version: '1.0'
  title: d1-ecom_dcs-outbound-api
servers:
  - url: 'https://YOUR_PROD_DOMAIN_NAME'
    description: Production server
  - url: 'https://YOUR_STAGING_DOMAIN_NAME'
    description: Staging server
paths:
  /oauth2/token:
    post:
      summary: Get Access Token
      description: This request is used by Thales to retrieve an access token to be used for outgoing API requests.<br/>Endpoint URL used for retrieving access token is configurable.
      operationId: getAccessToken
      parameters:
        - name: authorization
          in: header
          description: 'The authorization header includes a client secret in base64URL encoded format following this syntax: Basic "[clientId:client secret]" as per https://www.rfc-editor.org/rfc/rfc2617'
          required: true
          schema:
            type: string
            examples:
              - Basic aXNfdGJhbmswMToxMjM=
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/auth2Request'
      responses:
        '200':
          description: Default allowed response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth2Response'
        '400':
          description: |-
            Bad Request - Not Retryable
            |Error Code|Description|
            |-------|-------|            
            | FIELD_INVALID_FORMAT |  JSON not well formatted or one field is not expected format as defined in this documentation (first found) |

            -----------------
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      servers:
        - url: 'https://YOUR_PROD_DOMAIN_NAME'
          description: Production server
        - url: 'https://YOUR_STAGING_DOMAIN_NAME'
          description: Staging server
  '/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/notify-update':
    post:
      tags:
        - Token Management
      summary: Notify token update
      description: Notify token update.
      operationId: notifyTokenUpdate
      parameters:
        - $ref: '#/components/parameters/x-correlation-id-header'
        - $ref: '#/components/parameters/merchant-gateway-id-path'
        - $ref: '#/components/parameters/merchant-id-path'
        - $ref: '#/components/parameters/token-id-path'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notifyTokenUpdateRequest'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          description: |-
            Bad Request - Not Retryable
            |Error Code|Description|
            |-------|-------|            
            | FIELD_INVALID_FORMAT |  JSON not well formatted or one field is not expected format as defined in this documentation (first found) |

            -----------------
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: |-
            Bad Request - Not Retryable

            |Error Code|Description|
            |-------|-------|
            |UNKNOWN_TOKEN|Not able to identify the token.|
            |UNKNOWN_MERCHANT|Not able to identify the merchant.|

            -----------------
        '500':
          description: |-
            Bad Request - Not Retryable

            |Error Code|Description|
            |-------|-------|
            | INTERNAL_ERROR |  Internal Merchant Gateway error |
            | MERCHANT_ERROR  |  An error occurred with Merchant |

            -----------------
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '503':
          $ref: '#/components/responses/503'
      security:
        - clientCredsOAuth: []
      servers:
        - url: 'https://YOUR_PROD_DOMAIN_NAME'
          description: Production server
        - url: 'https://YOUR_STAGING_DOMAIN_NAME'
          description: Staging server
tags:
  - name: Token Management
  - name: Token Migration
  - name: Oauth2
components:
  parameters:
    merchant-gateway-id-path:
      name: merchantGatewayId
      in: path
      description: The merchant gateway identifier
      required: true
      schema:
        $ref: '#/components/schemas/merchantGatewayId'
    merchant-id-path:
      name: merchantId
      in: path
      description: The merchant identifier
      required: true
      schema:
        $ref: '#/components/schemas/merchantId'
    token-id-path:
      name: tokenId
      in: path
      description: The token identifier
      required: true
      schema:
        $ref: '#/components/schemas/tokenId'
    x-correlation-id-header:
      name: x-correlation-id
      in: header
      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.
      required: true
      schema:
        type: string
        pattern: '^[A-Za-z0-9_-]{1,64}$'
  securitySchemes:
    clientCredsOAuth:
      type: oauth2
      description: 'OAUTH activation for outbound endpoints is optional and part of D1 Tenant configuration (i.e. Token URL, Credentials, Scope).<br/>A merchant gateway entity wishing to opt for OAUTH scheme needs to support an endpoint (Token URL) from which the access token can be retrieved.<br/>This endpoint shall support HTTP POST Client Credentials grant requests in <b>x-www-form-urlencoded</b> content type as specified here: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.2'
      flows:
        clientCredentials:
          refreshUrl: N/A
          scopes: {}
          tokenUrl: '${tokenPath}'
  responses:
    '204':
      description: No Content
    '401':
      description: Unauthorized - Not Retryable
    '503':
      description: Service Unavailable - Retryable
  schemas:
    auth2Request:
      type: object
      title: Authorization request body
      properties:
        grant_type:
          const: client_credentials
        scope:
          type: string
          description: 'Access request scope as optionally defined by the merchant gateway '
      required:
        - grant_type
    auth2Response:
      type: object
      properties:
        access_token:
          $ref: '#/components/schemas/access_token'
        expires_in:
          $ref: '#/components/schemas/expires_in'
        token_type:
          $ref: '#/components/schemas/token_type'
        scope:
          $ref: '#/components/schemas/scope'
        expires_at:
          $ref: '#/components/schemas/expires_at'
    access_token:
      type: string
      description: The access_token that will be used to call the APIs.
      examples:
        - ey...HRT6LOON7w
    expires_in:
      type: number
      description: Remaining time in seconds for the access_token to expire.
      examples:
        - 900
    token_type:
      type: string
      description: Type of the access_token that will be used to call the APIs.
      examples:
        - Bearer
    scope:
      type: string
      description: Scope of the access_token.
    expires_at:
      type: string
      description: Access token expiration timestamp
      examples:
        - '2023-06-06T05:05:59.711Z'
    error:
      type: object
      additionalProperties: false
      properties:
        errorCode:
          type: string
          description: The type of error
          examples:
            - FIELD_INVALID_FORMAT
        error:
          type: string
          description: |-
            Provide additional information about the error if possible.<br/>
            Used for logging and troubleshooting purpose. It can change at any time so MUST NOT be parsed, and is not supposed to be human readable so CANNOT be displayed to end users.
    notifyTokenUpdateRequest:
      type: object
      properties:
        updateType:
          type: string
          enum:
            - TOKEN_STATE_CHANGE
            - CARD_UPDATE
      required:
        - updateType
    merchantGatewayId:
      type: string
      description: Merchant Gateway Identifier.
      pattern: '^[A-Za-z0-9_-]{10}$'
      minLength: 10
      maxLength: 10
      examples:
        - MGW_000001
    merchantId:
      type: string
      description: Merchant Identifier (aka Token Requestor ID) generated by the scheme TSP for that merchant.
      pattern: '^[A-Za-z0-9_-]{11}$'
      minLength: 11
      maxLength: 11
      examples:
        - '10610027312'
    tokenId:
      type: string
      description: Token unique identifier
      pattern: '^[A-Za-z0-9_-]{1,48}$'
      minLength: 1
      maxLength: 48
      examples:
        - 01fb32ff-5ed0-497f-8835-6af0916f29c0
