> ## Documentation Index
> Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate OOB Authentication Challenge

> In Out-of-Band (OOB) authentication flow, Enfuce sends an authentication challenge webhook notification to the issuer's registered endpoint for cardholder's approval.




## OpenAPI

````yaml json-files/threeds-oob-v1.openapi.json post /v1/3ds/oob/challenge/initiate
openapi: 3.0.3
info:
  title: 3DS OOB Outgoing Webhook API
  description: >
    The 3DS Authentication API supports OOB (out of band) authentication during
    3DS payment processing,

    where the client's own cardholder authentication service is used.


    All endpoints use HTTP response codes; requests and responses are UTF-8
    encoded in JSON format.

    A client must be able to handle new elements added to either the request or
    response without breaking.



    **Timeout**: The 3rd party authentication system has 150 seconds (default,
    configurable during 3DS setup) to send a callback with the

    authentication challenge result. After this, Enfuce responds with a timeout
    to ACS and end user authentication fails.


    **CustomerNumber** in this context is equal to `cardholder.customerNumber`
    in other parts of the Enfuce API.


    ## 3DS OOB Authentication flow


    ```
      Payment Network          Enfuce 3DS API                            Client System
             |                       |                                          |
             |-- 3ds auth request -->|                                          |  (1)
             |                       |-- POST /v1/3ds/oob/challenge/initiate  ->|  (2)
             |                       |<-------------- HTTP 200 OK --------------|  (3)
             |                       |                                          |
             |                       |                               authenticate cardholder
             |                       |                                          |
             |                       |<-- POST /v1/3ds/challenge/oob/result  ---|  (4)
             |<- 3ds auth response --|                                          |  (5)
    ```


    1. Enfuce receives a 3DS authentication request from the payment network
    including merchant information.

    2. Enfuce calls the client system, requesting a cardholder authentication.
       - The request contains both `authenticationId` and `challengeId` (UUIDs) that the client system uses when sending the challenge result back.
       - It also contains the customerNumber and other contextual info.
    3. The client system must return an HTTP 200 OK response within 2 seconds.

    4. Once the client system has a result from the cardholder authentication,
    it calls the "Submit authentication challenge result" endpoint,
       which needs to happen within 150 seconds from the start.
    5. Enfuce responds to the payment network, and the authorization process can
    proceed.
  version: 1.0.0
servers:
  - url: https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/processor
    description: UAT Sandbox
  - url: https://api.{{tenant}}.eu.live.prod.mycore.enfuce.com/processor
    description: Production
security: []
tags:
  - name: OOB Authentication Challenge Webhook Notification
paths:
  /v1/3ds/oob/challenge/initiate:
    post:
      tags:
        - OOB Authentication Challenge Webhook Notification
      summary: Initiate OOB Authentication Challenge
      description: >
        In Out-of-Band (OOB) authentication flow, Enfuce sends an authentication
        challenge webhook notification to the issuer's registered endpoint for
        cardholder's approval.
      operationId: initiateAuthenticationChallenge
      requestBody:
        $ref: '#/components/requestBodies/initiateAuthenticationChallengeBody'
      responses:
        '204':
          description: Authentication challenge acknowledged
        4XX:
          description: Client error
        5XX:
          description: Server error
      security:
        - basicAuth: []
components:
  requestBodies:
    initiateAuthenticationChallengeBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/initiateAuthenticationChallengeBody'
  schemas:
    initiateAuthenticationChallengeBody:
      type: object
      required:
        - authenticationId
        - challengeId
        - card
        - cardholder
      properties:
        authenticationId:
          type: string
          format: uuid
          description: Unique identifier of the authentication request.
        challengeId:
          type: string
          format: uuid
          description: Unique challenge identifier of this authentication step.
        cardholder:
          type: object
          required:
            - id
            - customerNumber
          properties:
            id:
              type: string
              format: uuid
              description: Unique identification number of the cardholder.
            customerNumber:
              type: string
              description: >-
                Unique identifier of the cardholder in other parts of the Enfuce
                API.
        card:
          type: object
          required:
            - id
            - maskedPan
          properties:
            id:
              type: string
              format: uuid
              description: Unique identification number of the card.
              example: b7e2a1d4-3f8c-4e29-91bc-0d5a6f2e8c47
            maskedPan:
              type: string
              description: Truncated card number.
              example: 342170******9554
        threeDsTransaction:
          $ref: '#/components/schemas/threeDsTransaction'
        merchant:
          $ref: '#/components/schemas/merchant'
    threeDsTransaction:
      type: object
      required:
        - deviceChannel
        - processedDateTime
      properties:
        transactionAmount:
          $ref: '#/components/schemas/money'
        category:
          type: string
          description: |
            Transaction category:
            - `PAYMENT` — Payment authentication
            - `NON_PAYMENT` — Non-payment authentication
          enum:
            - PAYMENT
            - NON_PAYMENT
          example: PAYMENT
        deviceChannel:
          type: string
          description: |
            Channel where the transaction is initiated:
            - `APP` — App-based
            - `BROWSER` — Browser-based
            - `REQUESTOR_INITIATED` — 3DS Requestor Initiated
          enum:
            - APP
            - BROWSER
            - REQUESTOR_INITIATED
          example: BROWSER
        processedDateTime:
          type: string
          format: date-time
          example: '2026-04-23T10:42:00.000Z'
          description: Time when the transaction is processed by Enfuce.
    merchant:
      type: object
      properties:
        name:
          type: string
          description: Merchant name
          example: Airline of the world inc.
        country:
          $ref: '#/components/schemas/country'
        url:
          type: string
          description: Merchant URL
          example: https://www.airline.com/order/64674
    money:
      type: object
      description: Amount including currency
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          example: 3.14
        currency:
          $ref: '#/components/schemas/currency'
    country:
      type: string
      description: >-
        The country where the transaction or withdrawal has occurred, or where
        the merchant is registered.
      pattern: '[A-Z]{3}'
      example: FIN
    currency:
      type: string
      description: A valid ISO 4217 currency code
      pattern: '[A-Z]{3}'
      example: EUR
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

````