​
AUTHENTICATED

Fired when the authentication to a merchant is successful. You should call Switch Card or Switch Card JWE within 15 seconds when you receive this webhook and send_card = true.

There are certain cases where send_card = false, for example while users interact with other Knot products or for the MassSwitcher feature.

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

​
CARD_UPDATING

Fired when a card update in a merchant account begins.

{
  "event": "CARD_UPDATING",
  "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
}

​
CARD_UPDATED

Fired when a card is updated in a merchant account.

{
  "event": "CARD_UPDATED",
  "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
}

​
CARD_FAILED

Fired when a card failed to be updated in a merchant account. The reason is specified in the reason field.

{
  "event": "CARD_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",
    "reason": "card expired"
  },
  "timestamp": 1710864923198
}

​
Failure Reasons

ReasonDescription
accountThe user’s merchant account has an issue (e.g. a foreign account).
cardThe user’s card information has an issue (e.g. incorrect phone #, incorrect billing address, unsupported card type, etc.).
card expiredThe user’s card is expired.
insufficient fundsThe user’s depository account associated with their card does not have sufficient funds to cover the pre-authorization hold from the merchant.
subscriptionThe user’s merchant account does not have an active subscription.
subscription adminThe user is not have the necessary authorization to update the payment method in the merchant account.
third-party payment method on subscriptionThe user pays for the merchant’s service through a 3rd party merchant account (e.g. Spotify through Hulu).
too close to end of billing cycleThe user’s billing cycle date is too close.
too many attemptsThe user attempted to enter their login credentials (e.g. username, password, OTP) to the merchant account too many times.
credentialsThe user entered incorrect credentials when logging in to the merchant.
otpThe user entered an incorrect OTP code when logging in to the merchant.
credentials timeoutThe user did not enter their login credentials to the merchant account in a certain period of time.
otp timeoutThe user did not enter their otp code to the merchant account in a certain period of time.
questions timeoutThe user did not enter the answers to the security questions for the merchant account in a certain period of time.
zip timeoutThe user did not enter their zip code associated with their merchant account in a certain period of time.
session not authenticatedKnot could not authenticate to the user’s merchant account.
did not receive payment method informationKnot did not receive any card information.
could not handle payment method informationKnot encountered an error handling the user’s card information once received.
could not retrieve payment method informationKnot was unsuccessful in retrieving payment method information from from a direct processor integration.
otherAn unknown issue was encountered.