adyen-openapi/yaml/BalancePlatformAcsNotification-v1.yaml

openapi: 3.1.0
info:
  version: '1'
  x-publicVersion: true
  title: 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
- name: Out-of-band
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:
              schema:
                $ref: '#/components/schemas/BalancePlatformNotificationResponse'
          description: OK - the request has succeeded.
  balancePlatform.authentication.relayed:
    post:
      tags:
      - Out-of-band
      summary: Out-of-band authentication requested
      description: 'Adyen sends this webhook when a cardholder must perform [out-of-band
        authentication](https://docs.adyen.com/issuing/3d-secure/oob-auth-sdk/authenticate-cardholders).


        To complete the authentication process, respond to this webhook with an **HTTP
        200** response. Include the `authenticationDecision` in the response body.


        If we do not receive the response within two seconds, the authentication process
        stops.'
      x-addedInVersion: '1'
      operationId: post-balancePlatform.authentication.relayed
      x-sortIndex: 2
      x-methodName: outofbandAuthenticationRequested
      security:
      - BasicAuth: []
      requestBody:
        content:
          application/json:
            examples:
              post-balancePlatform.authentication.relayed:
                $ref: '#/components/examples/post-balancePlatform.authentication.relayed-post-balancePlatform.authentication.relayed'
            schema:
              $ref: '#/components/schemas/RelayedAuthenticationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                post-balancePlatform.authentication.relayed:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/RelayedAuthenticationResponse'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
          description: Internal Server Error - the server could not process the request.
components:
  schemas:
    Amount:
      additionalProperties: false
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#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#minor-units).
          format: int64
          type: integer
      required:
      - value
      - currency
      type: object
    AuthenticationDecision:
      additionalProperties: false
      properties:
        status:
          description: "The status of the authentication. \n\nPossible values: \n\n\
            * **refused** \n\n* **proceed** \n\nFor more information, refer to [Authenticate\
            \ cardholders using the Authentication SDK](https://docs.adyen.com/issuing/3d-secure/oob-auth-sdk/authenticate-cardholders/)."
          enum:
          - proceed
          - refused
          type: string
      required:
      - status
      type: object
    AuthenticationInfo:
      additionalProperties: false
      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'
          - 08
          - 09
          - '80'
          - '82'
          type: string
        createdAt:
          description: "Date and time in UTC of the cardholder authentication. \n\n\
            [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'
          - 08
          - 09
          - '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:
      additionalProperties: false
      properties:
        authentication:
          description: Contains information about the authentication.
          $ref: '#/components/schemas/AuthenticationInfo'
        balancePlatform:
          description: The unique identifier of the balance platform.
          type: string
        id:
          description: The unique identifier of the authentication.
          type: string
        paymentInstrumentId:
          description: The unique identifier of the payment instrument that was used
            for the authentication.
          type: string
        purchase:
          description: Contains 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:
      additionalProperties: false
      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
        timestamp:
          description: When the event was queued.
          format: date-time
          type: string
        type:
          description: Type of notification.
          enum:
          - balancePlatform.authentication.created
          type: string
      required:
      - environment
      - type
      - data
      type: object
    BalancePlatformNotificationResponse:
      additionalProperties: false
      properties:
        notificationResponse:
          description: Respond with any **2xx** HTTP status code to [accept the webhook](https://docs.adyen.com/development-resources/webhooks#accept-notifications).
          type: string
      type: object
    ChallengeInfo:
      additionalProperties: false
      properties:
        challengeCancel:
          description: "Indicator informing the Access Control Server (ACS) and the\
            \ Directory Server (DS) that the authentication has been cancelled. Possible\
            \ values:\n* **00**: Data element is absent or value has been sent back\
            \ with the key `challengeCancel`.\n* **01**: Cardholder selected **Cancel**.\n\
            * **02**: 3DS Requestor cancelled Authentication.\n* **03**: Transaction\
            \ abandoned.\n* **04**: Transaction timed out at ACS \u2014 other timeouts.\n\
            * **05**: Transaction timed out at ACS \u2014 first CReq not received\
            \ by ACS.\n* **06**: Transaction error.\n* **07**: Unknown.\n* **08**:\
            \ Transaction time out at SDK."
          enum:
          - '00'
          - '01'
          - '02'
          - '03'
          - '04'
          - '05'
          - '06'
          - '07'
          - 08
          type: string
        flow:
          description: 'The flow used in the challenge. Possible values:


            * **PWD_OTP_PHONE_FL**: one-time password (OTP) flow via SMS

            * **PWD_OTP_EMAIL_FL**: one-time password (OTP) flow via email

            * **OOB_TRIGGER_FL**: out-of-band (OOB) flow'
          enum:
          - PWD_OTP_PHONE_FL
          - PWD_OTP_EMAIL_FL
          - OOB_TRIGGER_FL
          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
    Purchase:
      additionalProperties: false
      properties:
        date:
          description: The time of the purchase.
          format: date-time
          type: string
        merchantName:
          description: The name of the merchant.
          type: string
        originalAmount:
          description: The amount of the purchase in the original currency.
          $ref: '#/components/schemas/Amount'
      required:
      - date
      - merchantName
      - originalAmount
      type: object
    PurchaseInfo:
      additionalProperties: false
      properties:
        date:
          description: The date of the purchase.
          type: string
        merchantName:
          description: The name of the business that the cardholder purchased from.
          type: string
        originalAmount:
          description: The amount of the purchase.
          $ref: '#/components/schemas/Amount'
      required:
      - merchantName
      - date
      - originalAmount
      type: object
    RelayedAuthenticationRequest:
      additionalProperties: false
      properties:
        id:
          description: The unique identifier of the challenge.
          type: string
        paymentInstrumentId:
          description: The unique identifier of the [payment instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/paymentInstruments/_id_)
            used for the purchase.
          type: string
        purchase:
          description: The details of the purchase.
          $ref: '#/components/schemas/Purchase'
      required:
      - id
      - purchase
      - paymentInstrumentId
      type: object
    RelayedAuthenticationResponse:
      additionalProperties: false
      properties:
        authenticationDecision:
          description: The decision regarding the authentication.
          $ref: '#/components/schemas/AuthenticationDecision'
      required:
      - authenticationDecision
      type: object
    Resource:
      additionalProperties: false
      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
    ServiceError:
      additionalProperties: false
      properties:
        errorCode:
          description: The error code mapped to the error message.
          type: string
        errorType:
          description: The category of the error.
          type: string
        message:
          description: A short explanation of the issue.
          type: string
        pspReference:
          description: The PSP reference of the payment.
          type: string
        status:
          description: The HTTP response status.
          format: int32
          type: integer
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
  examples:
    WebhookAck:
      summary: 'Respond with your out-of-band authentication decision: "proceed" to
        continue, "refused" to refuse'
      value:
        authenticationDecision:
          status: proceed
    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
        timestamp: '2022-12-22T15:42:03+01:00'
        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
        timestamp: '2022-12-22T15:42:03+01:00'
        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
          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
        timestamp: '2022-12-22T15:42:03+01:00'
        type: balancePlatform.authentication.created
    post-balancePlatform.authentication.relayed-post-balancePlatform.authentication.relayed:
      summary: Out-of-band authentication relayed request webhook
      description: Example webhook for an out-of-band authentication relayed request
        webhook
      value:
        id: 1ea64f8e-d1e1-4b9d-a3a2-3953e385b2c8
        paymentInstrumentId: PI123ABCDEFGHIJKLMN45678
        purchase:
          date: '2025-03-06T15:17:55Z'
          merchantName: widgetsInc
          originalAmount:
            currency: EUR
            value: 14548