Adyen Authentication Webhooks API

openapi: 3.1.0
info:
  version: '1'
  x-publicVersion: true
  title: Adyen Authentication Webhooks
  description: >-
    Adyen sends webhooks to inform your system about events related to
    cardholder authentication.
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
tags:
  - name: General
webhooks:
  balancePlatform.authentication.created:
    post:
      tags:
        - General
      summary: Cardholder authenticated
      description: >-
        Adyen sends this webhook when the process of cardholder authentication
        is finalized, whether it is completed successfully, fails, or expires.
      x-addedInVersion: '1'
      operationId: post-balancePlatform.authentication.created
      x-sortIndex: 1
      x-methodName: cardholderAuthenticated
      security:
        - BasicAuth: []
      requestBody:
        content:
          application/json:
            examples:
              balancePlatform-authentication-created-authenticated-challenge:
                $ref: >-
                  #/components/examples/post-balancePlatform.authentication.created-balancePlatform-authentication-created-authenticated-challenge
              balancePlatform-authentication-created-authenticated-frictionless:
                $ref: >-
                  #/components/examples/post-balancePlatform.authentication.created-balancePlatform-authentication-created-authenticated-frictionless
              balancePlatform-authentication-created-rejected:
                $ref: >-
                  #/components/examples/post-balancePlatform.authentication.created-balancePlatform-authentication-created-rejected
            schema:
              $ref: '#/components/schemas/AuthenticationNotificationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                balancePlatform-authentication-created-authenticated-challenge:
                  $ref: '#/components/examples/WebhookAck'
                balancePlatform-authentication-created-authenticated-frictionless:
                  $ref: '#/components/examples/WebhookAck'
                balancePlatform-authentication-created-rejected:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/BalancePlatformNotificationResponse'
          description: OK - the request has succeeded.
components:
  schemas:
    Amount:
      properties:
        currency:
          description: >-
            The three-character [ISO currency
            code](https://docs.adyen.com/development-resources/currency-codes).
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: >-
            The amount of the transaction, in [minor
            units](https://docs.adyen.com/development-resources/currency-codes).
          format: int64
          type: integer
      required:
        - value
        - currency
      type: object
    AuthenticationInfo:
      properties:
        acsTransId:
          description: >-
            Universally unique transaction identifier assigned by the Access
            Control Server (ACS) to identify a single transaction.
          type: string
        challenge:
          description: >-
            Information about Strong Customer Authentication (SCA). Returned
            when `type` is **challenge**.
          $ref: '#/components/schemas/ChallengeInfo'
        challengeIndicator:
          description: >
            Specifies a preference for receiving a challenge. Possible values:


            * **01**: No preference

            * **02**: No challenge requested

            * **03**: Challenge requested (preference)

            * **04**: Challenge requested (mandate)

            * **05**: No challenge requested (transactional risk analysis is
            already performed)

            * **07**: No challenge requested (SCA is already performed)

            * **08**: No challenge requested (trusted beneficiaries exemption of
            no challenge required)

            * **09**: Challenge requested (trusted beneficiaries prompt
            requested if challenge required)

            * **80**: No challenge requested (secure corporate payment with
            Mastercard)

            * **82**: No challenge requested (secure corporate payment with
            Visa)
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '07'
            - 8
            - 9
            - '80'
            - '82'
          type: string
        createdAt:
          description: >-
            Date and time in UTC of the cardholder authentication. 


            [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format:
            YYYY-MM-DDThh:mm:ss+TZD, for example, **2020-12-18T10:15:30+01:00**.
          format: date-time
          type: string
        deviceChannel:
          description: >-
            Indicates the type of channel interface being used to initiate the
            transaction. Possible values:


            * **app**

            * **browser**

            * **3DSRequestorInitiated** (initiated by a merchant when the
            cardholder is not available)
          enum:
            - app
            - browser
            - ThreeDSRequestorInitiated
          type: string
        dsTransID:
          description: >-
            Universally unique transaction identifier assigned by the DS (card
            scheme) to identify a single transaction.
          type: string
        exemptionIndicator:
          description: >
            Indicates the exemption type that was applied to the authentication
            by the issuer, if exemption applied. Possible values:


            * **lowValue**

            * **secureCorporate**

            * **trustedBeneficiary**

            * **transactionRiskAnalysis**

            * **acquirerExemption**

            * **noExemptionApplied**

            * **visaDAFExemption**
          enum:
            - lowValue
            - secureCorporate
            - trustedBeneficiary
            - transactionRiskAnalysis
            - acquirerExemption
            - noExemptionApplied
            - visaDAFExemption
          type: string
        inPSD2Scope:
          description: Indicates if the purchase was in the PSD2 scope.
          type: boolean
        messageCategory:
          description: >-
            Identifies the category of the message for a specific use case.
            Possible values:


            * **payment**

            * **nonPayment**
          enum:
            - payment
            - nonPayment
          type: string
        messageVersion:
          description: >-
            The `messageVersion` value as defined in the 3D Secure 2
            specification.
          type: string
        riskScore:
          description: Risk score calculated from the transaction rules.
          format: int32
          type: integer
        threeDSServerTransID:
          description: >-
            The `threeDSServerTransID` value as defined in the 3D Secure 2
            specification.
          type: string
        transStatus:
          description: >
            The `transStatus` value as defined in the 3D Secure 2 specification.
            Possible values:


            * **Y**: Authentication / Account verification successful.

            * **N**: Not Authenticated / Account not verified. Transaction
            denied.

            * **U**: Authentication / Account verification could not be
            performed.

            * **I**: Informational Only / 3D Secure Requestor challenge
            preference acknowledged.

            * **R**: Authentication / Account verification rejected by the
            Issuer.
          enum:
            - 'Y'
            - 'N'
            - R
            - I
            - U
          type: string
        transStatusReason:
          description: >-
            Provides information on why the `transStatus` field has the
            specified value. For possible values, refer to [our
            docs](https://docs.adyen.com/online-payments/3d-secure/api-reference#possible-transstatusreason-values).
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
            - 8
            - 9
            - '10'
            - '11'
            - '12'
            - '13'
            - '14'
            - '15'
            - '16'
            - '17'
            - '18'
            - '19'
            - '20'
            - '21'
            - '22'
            - '23'
            - '24'
            - '25'
            - '26'
            - '80'
            - '81'
            - '82'
            - '83'
            - '84'
            - '85'
            - '86'
            - '87'
            - '88'
          type: string
        type:
          description: |-
            The type of authentication performed. Possible values:

            * **frictionless**
            * **challenge**
          enum:
            - frictionless
            - challenge
          type: string
      required:
        - challengeIndicator
        - dsTransID
        - messageVersion
        - threeDSServerTransID
        - transStatus
        - createdAt
        - type
        - inPSD2Scope
        - deviceChannel
        - messageCategory
        - acsTransId
      type: object
    AuthenticationNotificationData:
      properties:
        authentication:
          description: Information about the authentication.
          $ref: '#/components/schemas/AuthenticationInfo'
        balancePlatform:
          description: The unique identifier of the balance platform.
          type: string
        id:
          description: Unique identifier of the authentication.
          type: string
        paymentInstrumentId:
          description: >-
            Unique identifier of the payment instrument that was used for the
            authentication.
          type: string
        purchase:
          description: Information about the purchase.
          $ref: '#/components/schemas/PurchaseInfo'
        status:
          description: |-
            Outcome of the authentication.
            Allowed values:
            * authenticated
            * rejected
            * error
          enum:
            - authenticated
            - rejected
            - error
          type: string
      required:
        - id
        - paymentInstrumentId
        - status
        - authentication
        - purchase
      type: object
    AuthenticationNotificationRequest:
      properties:
        data:
          description: Contains event details.
          $ref: '#/components/schemas/AuthenticationNotificationData'
        environment:
          description: |-
            The environment from which the webhook originated.

            Possible values: **test**, **live**.
          type: string
        type:
          description: Type of notification.
          enum:
            - balancePlatform.authentication.created
          type: string
      required:
        - environment
        - type
        - data
      type: object
    BalancePlatformNotificationResponse:
      properties:
        notificationResponse:
          description: >-
            Respond with **HTTP 200 OK** and `[accepted]` in the response body
            to [accept the
            webhook](https://docs.adyen.com/development-resources/webhooks#accept-notifications).
          type: string
      type: object
    ChallengeInfo:
      properties:
        challengeCancel:
          description: >-
            Indicator informing the Access Control Server (ACS) and the
            Directory Server (DS) that the authentication has been cancelled.
            For possible values, refer to [3D Secure API
            reference](https://docs.adyen.com/online-payments/3d-secure/api-reference#mpidata).
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
          type: string
        flow:
          description: |-
            The flow used in the challenge. Possible values:

            * **OTP_SMS**: one-time password (OTP) flow
            * **OOB**: out-of-band (OOB) flow
          enum:
            - OTP_SMS
            - OOB
          type: string
        lastInteraction:
          description: The last time of interaction with the challenge.
          format: date-time
          type: string
        phoneNumber:
          description: The last four digits of the phone number used in the challenge.
          type: string
        resends:
          description: >-
            The number of times the one-time password (OTP) was resent during
            the challenge.
          format: int32
          type: integer
        retries:
          description: The number of retries used in the challenge.
          format: int32
          type: integer
      required:
        - flow
        - lastInteraction
      type: object
    PurchaseInfo:
      properties:
        date:
          description: Date of the purchase.
          type: string
        merchantName:
          description: Name of the merchant.
          type: string
        originalAmount:
          description: Amount of the purchase.
          $ref: '#/components/schemas/Amount'
      required:
        - merchantName
        - date
        - originalAmount
      type: object
    Resource:
      properties:
        balancePlatform:
          description: The unique identifier of the balance platform.
          type: string
        creationDate:
          description: >-
            The date and time when the event was triggered, in ISO 8601 extended
            format. For example, **2020-12-18T10:15:30+01:00**.
          format: date-time
          type: string
        id:
          description: The ID of the resource.
          type: string
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
  examples:
    WebhookAck:
      summary: Acknowledge Webhook
      value:
        notificationResponse: '[accepted]'
    post-balancePlatform.authentication.created-balancePlatform-authentication-created-authenticated-challenge:
      summary: Authentication successful (challenge flow)
      description: Example webhook for a successful authentication (challenge flow)
      value:
        data:
          authentication:
            acsTransId: 6a4c1709-a42e-4c7f-96c7-1043adacfc97
            challenge:
              flow: OOB
              lastInteraction: '2022-12-22T15:49:03+01:00'
            challengeIndicator: '01'
            createdAt: '2022-12-22T15:45:03+01:00'
            deviceChannel: app
            dsTransID: a3b86754-444d-46ca-95a2-ada351d3f42c
            exemptionIndicator: lowValue
            inPSD2Scope: true
            messageCategory: payment
            messageVersion: 2.2.0
            riskScore: 0
            threeDSServerTransID: 6edcc246-23ee-4e94-ac5d-8ae620bea7d9
            transStatus: 'Y'
            type: challenge
          balancePlatform: YOUR_BALANCE_PLATFORM
          id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
          paymentInstrumentId: PI3227C223222B5BPCMFXD2XG
          purchase:
            date: '2022-12-22T15:49:03+01:00'
            merchantName: TeaShop_NL
            originalAmount:
              currency: EUR
              value: 1000
          status: authenticated
        environment: test
        type: balancePlatform.authentication.created
    post-balancePlatform.authentication.created-balancePlatform-authentication-created-authenticated-frictionless:
      summary: Authentication successful (frictionless flow)
      description: Example webhook for a successful authentication (frictionless flow)
      value:
        data:
          authentication:
            acsTransId: 6a4c1709-a42e-4c7f-96c7-1043adacfc97
            challengeIndicator: '01'
            createdAt: '2022-12-22T15:45:03+01:00'
            deviceChannel: app
            dsTransID: a3b86754-444d-46ca-95a2-ada351d3f42c
            exemptionIndicator: lowValue
            inPSD2Scope: true
            messageCategory: payment
            messageVersion: 2.2.0
            riskScore: 0
            threeDSServerTransID: 6edcc246-23ee-4e94-ac5d-8ae620bea7d9
            transStatus: 'Y'
            type: frictionless
          balancePlatform: YOUR_BALANCE_PLATFORM
          id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
          paymentInstrumentId: PI3227C223222B5BPCMFXD2XG
          purchase:
            date: '2022-12-22T15:49:03+01:00'
            merchantName: TeaShop_NL
            originalAmount:
              currency: EUR
              value: 1000
          status: authenticated
        environment: test
        type: balancePlatform.authentication.created
    post-balancePlatform.authentication.created-balancePlatform-authentication-created-rejected:
      summary: Authentication rejected
      description: >-
        Example webhook for a rejected authentication due to exceeded number of
        retries
      value:
        data:
          balancePlatform: YOUR_BALANCE_PLATFORM
          creationDate: '2023-01-19T17:07:59+01:00'
          id: a8fc7a40-6e48-498a-bdc2-494daf0f490a
          authentication:
            acsTransId: a8fc7a40-6e48-498a-bdc2-494daf0f490a
            challenge:
              flow: OTP_SMS
              lastInteraction: '2023-01-19T17:37:13+01:00'
              phoneNumber: '******6789'
              resends: 0
              retries: 2
            challengeIndicator: '01'
            createdAt: '2023-01-19T17:07:17+01:00'
            deviceChannel: app
            dsTransID: 59de4e30-7f84-4a77-aaf8-1ca493092ef9
            exemptionIndicator: noExemptionApplied
            inPSD2Scope: false
            messageCategory: payment
            messageVersion: 2.2.0
            threeDSServerTransID: 8bc0fdbd-5c8a-4bed-a171-9d10347e7798
            transStatus: 'N'
            transStatusReason: '19'
            type: challenge
          paymentInstrumentId: PI3227C223222B5BPCMFXD2XG
          purchase:
            date: '2022-12-22T15:49:03+01:00'
            merchantName: TeaShop_NL
            originalAmount:
              currency: EUR
              value: 1000
          status: rejected
        environment: test
        type: balancePlatform.authentication.created