WEBHOOKS EVENTS

Klyrepay JSON API. For support, please email support@copaybenefits.com

Overview

The document provides an overview of the possible customer interaction/events that happens within the klyrepay system and can be reported via webhooks.

Support

For any technical support please contact support@copaybenefits.com

Events are categorized in two categories (financial and non-financial)

Non-Financial Events

Events that don’t report any financial activity or generated interactions with or around the patient.

** denotes repetitive events.

Event NameDescription
CardCreatedNotification whenever a new patient record is created. This is just a return of the ProcessCardHolderCreation API.
VerificationPageViewedNotification whenever the verification page is viewed.
UserCardVerifiedNotification whenever a patient verified their email address.**
UserCardVerificationFailedNotification whenever a patient fails email verification due to invalid OTP.**
ActivationPageViewedNotification whenever the activation page is viewed.
UserCardActivatedNotification whenever a patient activates their card.**
UserCardActivationFailedNotification whenever a patient fails Card Activation (i.e. because of invalid combination of email, lastname & debit card) and this is helpful for the call center agents to assist patients in looking up the debit card and providing correct information.**
CardSuspendedNotification whenever a patient card is suspended.**
CardUnSuspendedNotification whenever a patient card is unsuspended.**
ReplacementDebitCardCreatedNotification whenever a Replacement debit card is available on the patient account (i.e. This would only appear after a new debit card was requested using the ReplaceDebitCard API).

Financial Events

Event NameDescription
TransactionWhenever a Financial transaction on a card happens it will be reported with additional information related to the transaction. This can include things like the amount of the transaction, the merchant where the transaction took place, the date and time of the transaction, and more.

JSON Examples

Here are JSON examples for all the events listed above.

CardCreated

{
  "header": {
    "event_name": "CardCreated",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

VerificationPageViewed

{
  "header": {
    "event_name": "VerificationPageViewed",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

UserCardVerified

{
  "header": {
    "event_name": "UserCardVerified",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

UserCardVerificationFailed

{
  "header": {
    "event_name": "UserCardVerificationFailed",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

UserCardActivated

{
  "header": {
    "event_name": "UserCardActivated",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

ActivationPageViewed

{
  "header": {
    "event_name": "ActivationPageViewed",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

UserCardActivationFailed

{
    "header": {
      "eventname": "UserCardActivationFailed",
      "CustId": "ABC-123-489",
      "timestamp": "2022-12-31 23:59:59"
    },
    "data": {
      "provided_lastname": "Jane",
      "provided_dob": "1991-01-01",
      "provided_email": "patientemail@provider.tld",
      "error_code": "3",
      "error_description": "Invalid Email Address"
    }
  }

CardSuspended

{
  "header": {
    "event_name": "CardSuspended",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

CardUnSuspended

{
  "header": {
    "event_name": "CardUnSuspended",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

ReplacementDebitCardCreated

{
  "header": {
    "event_name": "ReplacementDebitCardCreated",
    "CustId": "ABC-123-489",
    "time_stamp": "2022-12-31 23:59:59"
  },
  "data": {}
}

Transaction

In the Transaction webhook, the tranaction_type will have the following possible values:

  • Payment
  • VoidPayment
  • Authorization
  • Approved (Settlement)
  • Declined
  • Reversal
{
    "header": {
      "event_name": "Transaction",
      "CustId": "ABC-123-489",
      "ProgramId": "ABC-123-489",
      "time_stamp": "2022-12-31 23:59:59"
    },
    "data": {
      "transaction_type": "Payment",
      "time_stamp": "2022-12-31 23:59:59",
      "vrx_id": "1234567",
      "transaction_id": "67ff3398-59c0-4b86-a49b-d4eff0b274c5",
      "amount": "10356",
 	"holds_amount": "10356",
 	"posted_balance": "0",
      "merchant_id": "program_user_name",
      "merchant_name": "Program Name",
      "merchant_city": "New Jersey",
      "merchant_state": "NJ",
      "mcc": "1234",
      "mcc_desc": "MCC code description",
      "reason_code": "0",
      "transaction_code": "XP20DS",
      "transaction_description": "VRX Reload"
    }
  }

Transaction Event Field Descriptions

FieldDescription
transaction_typeThe type of transaction, this will be one of the following: Payment, VoidPayment, Authorization, Approved, Declined, Reversal
time_stampTime stamp of the transaction in EST.
vrx_idInternal unique debit card identifier.
transaction_idInternal traceable transaction ID.
amountTransaction amount in cents (i.e. $1.00 = 100)
holds_amountAmount of open authorizations on the card.
posted_balanceBalance of the card after the transaction.
merchant_idMerchant ID
merchant_nameMerchant Name (or POS terminal name).
merchant_cityCity of Merchant
merchant_stateState of Merchant
mcc4 digit Merchant category codes
mcc_descMerchant category code description
reason_codeBank/processor level transaction approval/decline code.
transaction_codeVRX level transaction code. Different for all different transaction types. Authorizations and Approvals have multiple codes depending on how the transactions is done (online, phone or in person)
transaction_descriptionDescription associated with the transaction_code.

Possible Processor Error Codes

Error CodeDescription
10011Empty Authentication Details.
10012Invalid Authentication Details.
10000Invalid API request/Invalid JSON
10001Invalid Value for field FirstName, Provided Value Null
10002Invalid Value for field LastName, Provided Value Null
10003Invalid Value for field AddressLine1, Provided Value Null
10004Invalid Value for field City, Provided Value Null
10005Invalid Value for field State, Provided Value Null
10006Invalid Value for field Zip, Provided Value Null
10007Invalid Value for field Phone, Provided Value Null
10008Invalid Customer Id , Data Not found
10009Invalid Value for field Date Of Birth, Provided Value Null
10010Invalid Value for field VRXID, Provided Value Null
10013Duplicate CustId, CustId must be unique
10014Invalid Value for field DocId, Provided Value Null
10015Invalid Amount
10016Insufficient amount to load.
10017Card not created yet.
10018Invalid Program ID, the provided program doesn't exist.
10021No Card Issued for customer Id , Data Not found