Why Sharing Payer Events Matters

Merchants can improve the chargeback protection model's decisions by sending major events that payers take throughout the lifespan of the customer on your app. Anytime the customer makes a significant action on your app that allows you to collect information that identifies them, you may call our /events endpoints to share data with the chargeback model.

Implementing this endpoint is a critical step for any customer—especially those with:

High transaction volumes (>=$500K)
Those aiming to improve the accuracy of chargeback protection decisions

How It Helps with Chargeback Approval Rates

Our chargeback protection engine learns from both successful and failed user actions. When you provide lifecycle data like logins, verification steps, or sign-in failures, our models can:

Increase approval rates by identifying legitimate users more accurately (reducing false positives)
Prevent fraud by recognizing suspicious or automated behavior earlier (reducing false negatives)
Reduce your risk profile with card networks, minimizing the chance of being flagged for excessive chargebacks

Understanding Which Events to Pass

We've included some examples below to help your team determine when and how to trigger events. As a rule of thumb: if your system has enough confidence to identify the user or verify intent, it’s a good time to share an event. Engineering teams should ensure this data is sent automatically as part of your user workflows. This requires minimal engineering effort but can yield substantial returns in both revenue and risk mitigation.

Event	Description	Example Scenario
`SignUpEvent`	Triggered when a user successfully signs up on your platform.	A user creates a new account by entering their email and password. After registration completes, call `/events` with the sign-up data.
`SignInEvent`	Triggered when a user successfully logs into your platform.	A user logs in from a known browser or device. Each time a login is successful, call `/events` with identifying user data.
`SignInFailureEvent`	Triggered when a login attempt fails.	A user attempts to log in but enters the wrong password or logs in from a flagged device/IP. Call `/events` with identifying data and failure reason.
`BuyerChallengeEvent`	Used to report any buyer verification steps (e.g., email, SMS, KYC checks).	A user must verify their email, complete KYC, or enter an SMS code. After verification is completed, call `/ev

Example Requests for Events

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/events \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "eventType": "SignUp",
  "customerId": "user-123-abc",
  "country": "US",
  "username": "therock72",
  "email": "[email protected]",
  "firstName": "Dwayne",
  "lastName": "Johnson"
}
'

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/events \
     --header 'Authorization: YOU_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "eventType": "SignIn",
  "customerId": "user-123-abc",
  "country": "US",
  "email": "[email protected]"
}
'

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/events \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "eventType": "SignInFailure",
  "customerId": "user-123-abc",
  "country": "US",
  "email": "[email protected]",
  "failureReason": "Password Failed"
}
'

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/events \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "eventType": "BuyerChallenge",
  "type": "thirdPartyKyc",
  "status": "successfullyFulfilled",
  "customerId": "user-123-abc",
  "country": "US",
  "email": "[email protected]"
}
'