openapi: "3.1.0"
info:
  title: "Authentication callback web service server"
  description: |
    The callback API is used for Out of Band authentication like mobile application, when authentication is done outside ACS platform with an asynchronous method.
    Two similar endpoints are available: one for real-time transactions, and the other one for decoupled transactions.
  version: "25R1.1"
paths:
  /decoupled/authenticate:
    post:
      tags:
        - "decoupled"
      summary: "Finalize decoupled authentication"
      description: "Call back the decoupled authentication service to finalize a decoupled transaction."
      operationId: "authenticate"
      parameters:
        - $ref: '#/components/parameters/RequestIdentifierHeader'
        - $ref: '#/components/parameters/RequestDateHeader'
      requestBody:
        $ref: '#/components/requestBodies/CallbackRequest'
      responses:
        "204":
          description: "The message has been correctly processed."
        "4XX":
          description: "Bad request."
          $ref: '#/components/responses/CallbackResponse'
        "5XX":
          description: "Internal server error."
          $ref: '#/components/responses/CallbackResponse'
  /response/{sessionId}:
    post:
      tags:
        - "real-time"
      summary: "Update authentication status"
      description: "Call back the authentication service to update the authentication status."
      operationId: "callback"
      parameters:
        - $ref: '#/components/parameters/RequestIdentifierHeader'
        - $ref: '#/components/parameters/RequestDateHeader'
        - $ref: '#/components/parameters/SessionIdPath'
      requestBody:
        $ref: '#/components/requestBodies/CallbackRequest'
      responses:
        "204":
          description: "The message has been correctly processed."
        "4XX":
          description: "Bad request."
          $ref: '#/components/responses/CallbackResponse'
        "5XX":
          description: "Internal server error."
          $ref: '#/components/responses/CallbackResponse'
components:
  parameters:
    RequestDateHeader:
      name: "Request-date"
      description: "The UTC datetime at which the request has been issued, complying with the ISO 8601 datetime format."
      in: "header"
      required: true
      schema:
        type: "string"
        format: "yyyy-MM-dd'T'HH:mm:ss"
      example: "2015-07-02T20:07:59"
    RequestIdentifierHeader:
      name: "Request-identifier"
      description: "The unique identifier of the request. Used to correlate logs between Authentication HUB and the client."
      in: "header"
      required: true
      schema:
        type: "string"
        format: "uuid"
      example: "38400000-8cf0-11bd-b23e-10b96e4ef00e"
    SessionIdPath:
      name: "sessionId"
      description: "The identifier of the session/transaction."
      in: "path"
      required: true
      schema:
        type: "string"
        format: "uuid"
  requestBodies:
    CallbackRequest:
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/CallbackRequest'
              - $ref: '#/components/schemas/Signable'
  responses:
    CallbackResponse:
      description: "The response to a callback request in case of error."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CallbackResponse'
  schemas:
    CallbackRequest:
      type: "object"
      required:
        - "sessionId"
        - "status"
      properties:
        sessionId:
          description: "The identifier of the transaction (also called session)."
          type: "string"
          format: "uuid"
        status:
          description: "The status of the authentication."
          type: "string"
          enum:
            - "SUCCESS"
            - "FAILURE"
            - "PENDING"
        failureCause:
          description: "The cause of the failure. Required if the status is `FAILURE`."
          type: "string"
          enum:
            - "TIMEOUT"
            - "CANCEL"
            - "REFUSAL"
            - "TECHNICAL_ERROR"
        externalTransactionId:
          description: "The external reference of the transaction."
          type: "string"
          minLength: 1
          maxLength: 255
        authenticationMethod:
          description: |
            The authentication process used to calculate CAVV based on EMVCo 3DS protocol 2.
            Non-exhaustive list:
            - `01`: Static Passcode
            - `02`: SMS OTP
            - `03`: Key fob or EMV card reader OTP
            - `04`: App OTP
            - `05`: OTP Other
            - `06`: KBA
            - `07`: OOB Biometrics
            - `08`: OOB Login
            - `09`: OOB Other
            - `10`: Other
            - …
          type: "string"
          minLength: 2
          maxLength: 2
        freeContext:
          description: "A free map to forward any specific information to ACS platform."
          type: "object"
          additionalProperties:
            type: "string"
    CallbackResponse:
      type: "object"
      properties:
        sessionId:
          description: "The identifier of the concerned session."
          type: "string"
          format: "uuid"
        errorCode:
          description: |
            The 9-digits code to be matched against the dedicated documentation to be interpreted.
            The three first digits are the HTTP status code.
            Non-exhaustive list of possible values:
            - `400100000`: Bad request: invalid incoming request.
            - `400010001`: Bad parameter: sessionId.
            - `400090000`: Bad parameter: status.
            - `400090001`: Bad parameter: failureCause.
            - `400090002`: Bad parameter: externalTransactionId.
            - `400100100`: Found invalid signature in request.
            - `400090005`: Internal error.
            - `403000000`: The provided Api-Key is invalid or expired.
            - `403900000`: Request blocked by our firewall security policy. Could happen in case of mutual authentication error, incorrect URL, incorrect HTTP header, unexpected text, empty request body… Identifier in the message field is the error ID logged in our firewall.
            - `404011000`: Decoupled transaction not found.
            - `500100001`: Error during the signature verification process.
            - `500100002`: Missing or invalid signature key store.
            - `500100100`: Invalid signature configuration.
            - `500100101`: Unsupported signature algorithm.
            - `500011000`: Error during decoupled transaction processing.
            - `500011001`: Error during ACS call.
            - `500011002`: Error on ACS side.
            - `520000000`: Unexpected error.
          type: "string"
          pattern: "^\\d{9}$"
          minLength: 9
          maxLength: 9
    Signable:
      type: "object"
      properties:
        signature:
          type: "string"
          description: |
            Signature of the request.
            Required if the callback service is configured as such as per client demand.
            The signature format must be RFC 7515 (JSON Web Signature) and RFC 7797 (Unencoded or detached payload) compliant.
            As such, a typical signature should look like this: `[header]..[signature]`, where `[header]` is the Base64 URL encoding of the JOSE header which contains the key ID, algorithm and object type.
            For example: `eyJraWQiOiJzaWduIiwidHlwIjoiSk9TRStKU09OIiwiYWxnIjoiUlMyNTYifQ`, which in clear JSON gives: `{"kid":"sign","typ":"JOSE+JSON","alg":"RS256"}`.
            The "kid" (Key ID) and "alg" header fields are both required to perform the check.
            An additional "jku" parameter, with a JWKS URL where to retrieve the public key, can also be specified; if not, it should be expected for public keys to have been exchanged beforehand.
            The "typ" is only there by convention and should only be set to "JOSE" or "JOSE+JSON", since were are not dealing JWT (tokens) here.