​
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_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.

​
MERCHANT_STATUS_UPDATE

Listening to this event is only necessary if you intend to display and allow users to select various merchants natively inside your app.

Fired when a merchant becomes available or unavailable (even if temporarily), including when a brand new merchant is made available on the Knot platform for the first time.

Availability is unique to product types, platforms, and versions of the SDK. As such, the event will fire independently for each product type and platform. Particularly if you are implementing multiple of Knot’s products, you should consider the type property to determine whether a merchant is available for a given product, as availability can differ.

This event does not include a session_id, which is relevant when generating a hash map for webhook verification, as described in Webhook Verification.

{
  "event": "MERCHANT_STATUS_UPDATE",
  "merchant": {
    "id": 10,
    "name": "Uber",
	"category": "Transportation",
    "logo": "https:\/\/knot.imgix.net\/merchants\/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240"
  },
  "data": {
    "type": "card_switcher", // card_switcher, transaction_link
	"status": "UP", // UP, DOWN
    "platform": "ios", // ios, android, web
    "sdk": "1.0.0" // nullable
  },
  "timestamp": 1710864923198
}