Webhook Events

Webhook events list

Kulipa produces event details that can be relayed to notify you about activities in your account.

Whenever an event occurs, Kulipa creates a new Event entity. A singular API call might lead to the inception of several events. For instance, blocking a card results in event like card.blocked.

By defining webhook endpoints in your Kulipa profile, you grant Kulipa the capability to autonomously dispatch Event entities via POST requests to the webhook endpoint anchored in your system.
Once your webhook endpoint receives the Event, your system can execute backend operations
(such as, sending a notification to the end user regarding payment with their card).

Event Entity

The Event entity dispatched to your webhook endpoint offers a snapshot of the altered entity.

List of events

Common event payload schema

These event fields will be present on any Kulipa event

JSON

  eventTargetId: string, // uuid of the related object (e.g. card, cardAuthorization)
  eventId: string, // uuid of the webhook event
  eventName: string // Event enum list below
  // For user events and anything associated (cards, transactions, ...), a userId will also be provided.
  userId: string // User associated with this event (format is `usr-<uuid>`)

cardAuthorization.confirmed

Occurs whenever a payment with a card is confirmed.
A hold is placed on the relevant funds, but the transaction is still not final.

Suggested use : Display a notification to the user about a pending payment or refund

Schema:

JSON

{
  ...Common event fields
  merchantName: string, // Merchant name
  merchantMcc: string, // Merchant category code
  amount: number, // 2 decimals number
  currency: string, // Iso 4217 currency codes
  type: 'payment' | 'refund'
}

cardAuthorization.rejected

Occurs whenever a payment with a card is rejected.

Suggested use : Display a notification to the user

Schema:

JSON

{
  ...CommonEventFields,
  merchantName: string, // Merchant name
  merchantMcc: string, // Merchant category code
  amount: number, // 2 decimals number
  currency: string,// Iso 4217 currency codes
  type: 'payment'
  declineReasonCode: 'insufficientFund' | 'failedControl' | 'notActive' | 'incremental' | 'other', // Decline reason code
}

card.created

A card has been created for the user.

Suggested use : If a card was not created in the app recently, display a warning notification to the user.

Schema:

JSON

{
  ...CommonEventFields,
}

card.frozen

A user's card has been frozen.

Suggested use : If a card was not frozen in the app recently, display a warning notification to the user.

Schema:

JSON

{
  ...CommonEventFields,
}

card.unfrozen

A user's card has been unfrozen.

Suggested use : If a card was not unfrozen in the app recently, display a warning notification to the user.

Schema:

JSON

{
  ...CommonEventFields,
}

user.created

A new user has been created in the system.

Suggested use : If this is not expected, escalate to your support team.

Schema:

JSON

{
  ...CommonEventFields,
}

To be elaborated further

cardAuthorization.oobRequested

An OOB 3DS request has been sent - the user would need to respond to it in order to confirm the transaction.
(OOB 3DS is a second factor in-app authorization for online transactions)

Suggested use : Display a notification to the user asking them to confirm their transaction.

card.revoked

A user's card has been revoked.

Suggested use : If a card was not revoked (cancelled) in the app recently, display a warning notification to the user.

kyc.created

A new KYC request has been created for the user.

Suggested use : If this is not expected, escalate to your support team.

kyc.verified

The user's KYC has been verified successfully.

Suggested use : Display a notification guiding the user to create a card.

kyc.failed

The user's KYC request has been declined. Depending on the payload, a follow-on KYC needs to happen, or the user simply
cannot open a Kulipa account at this time.

Suggested use : Display a notification to the user.

kyc.expired

The user's KYC request has expired and in order to proceed with it, it must be renewed.

Suggested use : Contact Kulipa support.

kyc.revoked

The user's KYC request has been revoked. This means the KYC request has been closed prior to completion.

Suggested use : Contact Kulipa support.

user.limitApproaching

The user's spend limit (across all cards) is almost reached, and as a result some card transactions might be declined.

Suggested use : Display a notification to the user

wallet.lowAvailableBalance

The available balance in the user's wallet is very low and card transactions might be declined as a result.

Suggested use : Display a notification to the user

Events without a user ID attached

webhookSubscription.created

A webhook subscription has been created in the system. This event is provided in order to alert in case this is not expected.

Suggested use : If this is not expected, escalate to your support team.

webhookSubscription.verified

A webhook subscription has been verified (activated) in the system. This event is provided in order to alert in case this is not expected.

Suggested use : If this is not expected, escalate to your support team.

webhookSubscription.deleted

A webhook subscription has been deleted in the system. This event is provided in order to alert in case this is not expected.

Suggested use : If this is not expected, escalate to your support team.

webhookSubscription.updated

A webhook subscription has been updated in the system. This event is provided in order to alert in case this is not expected.

Suggested use : If this is not expected, escalate to your support team.

webhookSubscription.disabled

A webhook subscription has been disabled in the system. This event is provided in order to alert in case this is not expected.

Suggested use : If this is not expected, escalate to your support team.