{ "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).\n\nTo complete the authentication process, respond to this webhook with an **HTTP 200** response. Include the `authenticationDecision` in the response body.\n\nIf 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:\n\n* **01**: No preference\n* **02**: No challenge requested\n* **03**: Challenge requested (preference)\n* **04**: Challenge requested (mandate)\n* **05**: No challenge requested (transactional risk analysis is already performed)\n* **07**: No challenge requested (SCA is already performed)\n* **08**: No challenge requested (trusted beneficiaries exemption of no challenge required)\n* **09**: Challenge requested (trusted beneficiaries prompt requested if challenge required)\n* **80**: No challenge requested (secure corporate payment with Mastercard)\n* **82**: No challenge requested (secure corporate payment with Visa)\n", "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:\n\n* **app**\n* **browser**\n* **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:\n\n* **lowValue**\n* **secureCorporate**\n* **trustedBeneficiary**\n* **transactionRiskAnalysis**\n* **acquirerExemption**\n* **noExemptionApplied**\n* **visaDAFExemption**\n", "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:\n\n* **payment**\n* **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:\n\n* **Y**: Authentication / Account verification successful.\n* **N**: Not Authenticated / Account not verified. Transaction denied.\n* **U**: Authentication / Account verification could not be performed.\n* **I**: Informational Only / 3D Secure Requestor challenge preference acknowledged.\n* **R**: Authentication / Account verification rejected by the Issuer.\n", "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:\n\n* **frictionless**\n* **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" : "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.\nAllowed values:\n* authenticated\n* rejected\n* 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.\n\nPossible 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 — other timeouts.\n* **05**: Transaction timed out at ACS — 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:\n\n* **PWD_OTP_PHONE_FL**: one-time password (OTP) flow via SMS\n* **PWD_OTP_EMAIL_FL**: one-time password (OTP) flow via email\n* **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" : "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" }, "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 } } } } } } }