Guides

Merchant Authentication

Suggest Edits

CREDENTIALS_FAILED

Triggered when the login credentials used to login to a merchant are incorrect and the user needs to re-enter them (if a failed webhook is not received).

Request example

{
  "event": "CREDENTIALS_FAILED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
  "merchant": {
    "id": 11,
    "name": "Uber"
  },
  "data": {
    "card_id": "123456789"
  },
  "timestamp": 1710864923198
}

OTP_REQUIRED

Triggered when a user needs to enter an OTP code to login to a merchant for the 1st time.

Request example

{
  "event": "OTP_REQUIRED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
  "merchant": {
    "id": 11,
    "name": "Uber"
  },
  "data": {
    "card_id": "123456789"
  },
  "timestamp": 1710864923198
}

OTP_FAILED

Triggered when the OTP code used to login to a merchant is incorrect and the user needs to re-enter it (if a failed webhook is not received).

Request example

{
  "event": "OTP_FAILED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
  "merchant": {
    "id": 11,
    "name": "Uber"
  },
  "data": {
    "card_id": "123456789"
  },
  "timestamp": 1710864923198
}

QUESTIONS_REQUIRED

Triggered when a user needs to provide answers to security questions for the 1st time.

Request example

{
  "event": "QUESTIONS_REQUIRED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
  "merchant": {
    "id": 11,
    "name": "Uber"
  },
  "data": {
    "card_id": "123456789"
  },
  "timestamp": 1710864923198
}

QUESTIONS_FAILED

Triggered when the answers to security questions are incorrect and the user needs to re-enter the answers (if a failed webhook is not received).

Request example

{
  "event": "QUESTIONS_FAILED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
  "merchant": {
    "id": 11,
    "name": "Uber"
  },
  "data": {
    "card_id": "123456789"
  },
  "timestamp": 1710864923198
}

LOGIN_APPROVAL

Triggered when a user needs to approve the login to a merchant via a push notification, text message, or similar from a merchant.

Request example

{
  "event": "LOGIN_APPROVAL",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
  "merchant": {
    "id": 11,
    "name": "Uber"
  },
  "data": {
    "card_id": "123456789"
  },
  "timestamp": 1710864923198
}

AUTHENTICATED

Triggered when the authentication to a merchant is successful. You should call Switch Card when you receive this webhook. Optionally, also consider the send_card property as described below.

Request example

{
  "event": "AUTHENTICATED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
  "merchant": {
    "id": 11,
    "name": "Uber"
  },
  "data": {
    "card_id": "123456789",
    "send_card": true,
    "entrypoint": "onboarding"
  },
  "timestamp": 1710864923198
}

send_card property

If you would like to take advantage of Knot's MassSwitcher feature, you can optionally consider the send_card property when receiving the AUTHENTICATED webhook. By default, this property will be true, in which case your integration should send card information. This is the case for all merchants, except the merchant Google Keychain, which is used for the MassSwitcher feature. For the merchant Google Keychain, send_card = false because the user is simply authenticating to their keychain, not a specific merchant in which they would like to update their card. Therefore, when a user authenticates to the Google Keychain merchant, send_card = false in the AUTHENTICATED webhook and you do not need to send card information.

ACCOUNTS_RETRIEVED

Triggered when a user's merchant accounts are successfully retrieved from their Google Account. This event is specific to the MassSwitcher feature.

Request example

{
  "event": "ACCOUNTS_RETRIEVED",
  "session_id": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584",
  "task_id": 25605,
  "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
  "merchant": {
    "id": 11,
    "name": "Google Keychain"
  },
  "timestamp": 1710864923198
}

Updated about 1 month ago