Home / Basics / Events and Notifications

Events Reference

Overview

This guide is a reference for all Highnote notification events. Note the following when using this reference:

  • Notification events are categorized by domain. For example, the ACH section of this guide houses all notification events related to ACH transfers.
  • The NotificationEvent object in the Highnote API uses a NotificationEventName field to identify different event types. This field is not always the same name as the object used to create a notification event query.
  • When creating notification event queries, refer to the event's object in the Highnote API Reference. Each notification event in this reference links out to its corresponding object in the API.
  • For a description of each notification event, see the corresponding Object reference link in the reference tables in this guide.

ACH

ACH notification events are triggered for various ACH event types.

The following table provides an overview of some fields you may see in an ACH notification event response. Note that this table does not contain all response fields. For a full list of response fields, refer to the API Reference:

FieldDescription
amountThe amount of the ACH transfer
companyEntryDescriptionDescription of the type of ACH provided by the originator of the ACH transfer
companyIdentifierAn alphanumeric code used to identify the originator of the ACH transfer
companyNameName of the company that initiated the ACH transfer
fromStatusThe previous hold status of the ACH transfer; applies to ACH_HOLD events

ACH externally initiated deposit

ACH externally initiated deposit notifications are triggered when an incoming NACHA file credit transaction is processed. The following notification events are available for ACH externally initiated deposits:

Notification Event NameAPI Reference
ACH_EXTERNALLY_INITIATED_DEPOSIT_RECEIVEDObject reference
ACH_EXTERNALLY_INITIATED_DEPOSIT_PROCESSEDObject reference
ACH_EXTERNALLY_INITIATED_DEPOSIT_FAILEDObject reference

The following payload provides an example notification response from an ACH_EXTERNALLY_INITIATED_DEPOSIT_RECEIVED event:

ACH_EXTERNALLY_INITIATED_DEPOSIT_RECEIVED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-03-31T21:21:39.732Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "ACH_EXTERNALLY_INITIATED_DEPOSIT_RECEIVED",
      "node": {
        "__typename": "AchExternallyInitatedDepositReceivedEvent",
        "id": "ACH_EXTERNALLY_INITIATED_DEPOSIT_RECEIVED_EVENT_ID",
        "amount": {
          "currencyCode": "USD",
          "value": 60150
        },
        "companyEntryDescription": "ORDER",
        "companyIdentifier": "271111113",
        "companyName": "COMPANY COM INC",
        "createdAt": "2022-03-31T21:21:36.113Z",
        "financialAccountId": "FINANCIAL_ACCOUNT_ID",
        "settlementDate": "2022-01-29T05:00:00.000Z",
        "transactionId": "TRANSACTION_ID",
        "updatedAt": "2022-03-31T21:21:36.121Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1648761700155
  }
}

ACH externally initiated withdrawal

ACH externally initiated deposit events are triggered when an incoming NACHA file debit transaction is processed, and a fund out ACH payment transitions states. The following notification events are available for ACH externally initiated withdrawals:

Notification Event NameAPI Reference
ACH_EXTERNALLY_INITIATED_WITHDRAWAL_RECEIVEDObject reference
ACH_EXTERNALLY_INITIATED_WITHDRAWAL_PROCESSEDObject reference
ACH_EXTERNALLY_INITIATED_WITHDRAWAL_FAILEDObject reference

The following payload provides an example notification response from an ACH_EXTERNALLY_INITIATED_WITHDRAWAL_RECEIVED event:

ACH_EXTERNALLY_INITIATED_WITHDRAWAL
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-03-31T21:21:39.732Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "ACH_EXTERNALLY_INITIATED_WITHDRAWAL_RECEIVED",
      "node": {
        "__typename": "AchExternallyInitiatedWithdrawalReceivedEvent",
        "id": "ACH_EXTERNALLY_INITIATED_WITHDRAWAL_RECEIVED_EVENT_ID",
        "transactionId": "TRANSACTION_ID",
        "amount": {
          "currencyCode": "USD",
          "value": 60150
        },
        "createdAt": "2022-03-31T21:21:36.113Z",
        "updatedAt": "2022-03-31T21:21:36.121Z",
        "companyEntryDescription": "ORDER",
        "companyIdentifier": "271111113",
        "companyName": "HIGHNOTE",
        "financialAccountId": "HIGHNOTE_FINANCIAL_ACCOUNT_ID",
        "settlementDate": "2022-01-29T05:00:00.000Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1648761700155
  }
}

ACH funds deposit

ACH funds deposit notifications are triggered when a fund-in ACH transfer is initiated from within Highnote, or transitions states. The following notification events are available for ACH funds deposits:

Notification Event NameAPI Reference
ACH_FUNDS_DEPOSIT_INITIATEDObject reference
ACH_FUNDS_DEPOSIT_PROCESSINGObject reference
ACH_FUNDS_DEPOSIT_PROCESSEDObject reference
ACH_FUNDS_DEPOSIT_FAILEDObject reference
ACH_FUNDS_DEPOSIT_RETURNEDObject reference
ACH_FUNDS_DEPOSIT_CANCELEDObject reference

The following payload provides an example notification response from an ACH_FUNDS_DEPOSIT_INITIATED event:

ACH_FUNDS_DEPOSIT_INITIATED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-03-31T21:21:39.732Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "ACH_FUNDS_DEPOSIT_INITIATED",
      "node": {
        "__typename": "FundsDepositInitiatedEvent",
        "id": "FUNDS_DEPOSIT_INITIATED_EVENT_ID",
        "transactionId": "TRANSACTION_ID",
        "amount": {
          "currencyCode": "USD",
          "value": 60150
        },
        "createdAt": "2022-03-31T21:21:36.113Z",
        "updatedAt": "2022-03-31T21:21:36.121Z",
        "companyIdentifier": "271111113",
        "companyName": "HIGHNOTE",
        "fromFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "toFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "settlementDate": "2022-01-29T05:00:00.000Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1648761700155
  }
}

ACH funds withdrawal

ACH funds withdrawal events are triggered when a fund-out ACH payment is initiated from within Highnote, or transitions states. The following notification events are available for ACH funds withdrawals:

Notification Event NameAPI Reference
ACH_FUNDS_WITHDRAWAL_INITIATEDObject reference
ACH_FUNDS_WITHDRAWAL_PROCESSINGObject reference
ACH_FUNDS_WITHDRAWAL_PROCESSEDObject reference
ACH_FUNDS_WITHDRAWAL_FAILEDObject reference
ACH_FUNDS_WITHDRAWAL_RETURNEDObject reference
ACH_FUNDS_WITHDRAWAL_CANCELEDObject reference

The following payload provides an example notification response from an ACH_FUNDS_WITHDRAWAL_INITIATED event:

ACH_FUNDS_WITHDRAWAL_INITIATED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-03-31T21:21:39.732Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "ACH_FUNDS_WITHDRAWAL_INITIATED",
      "node": {
        "__typename": "FundsWithdrawalInitiatedEvent",
        "id": "FUNDS_WITHDRAWAL_INITIATED_EVENT_ID",
        "transactionId": "TRANSACTION_ID",
        "amount": {
          "currencyCode": "USD",
          "value": 60150
        },
        "createdAt": "2022-03-31T21:21:36.113Z",
        "updatedAt": "2022-03-31T21:21:36.121Z",
        "companyIdentifier": "271111113",
        "companyName": "HIGHNOTE",
        "fromFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "toFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "settlementDate": "2022-01-29T05:00:00.000Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1648761700155
  }
}

ACH hold

ACH hold notifications trigger when an ACH transfer has been put on hold, or has a hold removed from it. The following notification events are available for ACH holds:

Notification event nameAPI Reference
ACH_HOLD_ADDEDObject reference
ACH_HOLD_REMOVEDObject reference

The following payload provides an example notification response from an ACH_HOLD_ADDED event:

ACH_HOLD_ADDED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-03-31T21:21:39.732Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "ACH_HOLD_ADDED",
      "node": {
        "__typename": "AchHoldAddedEvent",
        "id": "ACH_HOLD_ADDED_EVENT_ID",
        "transactionId": "TRANSACTION_ID",
        "fromStatus": "PREVIOUS_HOLD_STATUS",
        "holdType": "RISK",
        "createdAt": "2022-03-31T21:21:36.113Z",
        "updatedAt": "2022-03-31T21:21:36.121Z",
        "companyIdentifier": "271111113",
        "companyName": "HIGHNOTE",
        "sourceAccountId": "FINANCIAL_ACCOUNT_ID",
        "receivingAccountId": "FINANCIAL_ACCOUNT_ID"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1648761700155
  }
}

ACH repayment

ACH repayment events are triggered when an ACH repayment transaction transitions states. The following notification events are available for ACH repayments:

Notification Event NameAPI Reference
ACH_REPAYMENT_PROCESSINGObject reference
ACH_REPAYMENT_PROCESSEDObject reference
ACH_REPAYMENT_RETURNEDObject reference
ACH_REPAYMENT_FAILEDObject reference

The following payload provides an example notification response from an ACH_REPAYMENT_PROCESSED event:

ACH_REPAYMENT_PROCESSED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-03-11T03:51:32.418Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "ACH_REPAYMENT_PROCESSED",
      "node": {
        "__typename": "RepaymentProcessedEvent",
        "id": "REPAYMENT_PROCESSED_EVENT_ID",
        "amount": {
          "currencyCode": "USD",
          "value": 9900
        },
        "companyIdentifier": "1852922649",
        "companyName": "HIGHNOTEPLATFORM",
        "createdAt": "2022-03-11T03:06:22.843Z",
        "fromFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "settlementDate": "2022-03-11T03:06:22.840Z",
        "toFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "transactionId": "TRANSACTION_ID",
        "fundsAvailableDate": "2022-03-11T03:06:22.840Z",
        "updatedAt": "2022-03-11T03:51:29.737Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1646970698504
  }
}

ACH secure deposit

ACH secure deposit events are triggered when an ACH secure deposit transitions states. The following notification events are available for ACH secure deposits:

Notification Event NameAPI Reference
ACH_SECURE_DEPOSIT_INITIATEDObject reference
ACH_SECURE_DEPOSIT_CANCELEDObject reference
ACH_SECURE_DEPOSIT_PROCESSINGObject reference
ACH_SECURE_DEPOSIT_PROCESSEDObject reference
ACH_SECURE_DEPOSIT_RETURNEDObject reference
ACH_SECURE_DEPOSIT_FAILEDObject reference

The following payload provides an example notification response from an ACH_SECURE_DEPOSIT_PROCESSING event:

ACH_SECURE_DEPOSIT_PROCESSING
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-05-02T15:17:39.303Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "ACH_SECURE_DEPOSIT_PROCESSING",
      "node": {
        "__typename": "SecureDepositProcessingEvent",
        "id": "SECURE_DEPOSIT_PROCESSING_EVENT_ID",
        "amount": {
          "currencyCode": "USD",
          "value": 66000
        },
        "companyIdentifier": "1852922649",
        "companyName": "HIGHNOTEPLATFORM",
        "createdAt": "2022-05-02T15:14:24.606Z",
        "fromFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "settlementDate": "2022-05-02T15:14:24.603Z",
        "toFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "transactionId": "TRANSACTION_ID",
        "updatedAt": "2022-05-02T15:14:24.606Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1651504665140
  }
}

Account holder information update

Account holder information update events are sent with an account holder or associated person's information is updated. The following events are available for account holder information updates:

Notification eventAPI Reference
PERSON_ACCOUNT_HOLDER_IDENTITY_UPDATEDObject reference
BUSINESS_ACCOUNT_HOLDER_IDENTITY_UPDATEDObject reference
BUSINESS_AUTHORIZED_PERSON_IDENTITY_UPDATEDObject reference
BUSINESS_ULTIMATE_BENEFICIAL_OWNER_IDENTITY_UPDATEDObject reference

In the event payload, the updatedTypes field shows what information was updated for the account holder. The following payload provides an example notification response of a PERSON_ACCOUNT_HOLDER_IDENTITY_UPDATED event:

PERSON_ACCOUNT_HOLDER_IDENTITY_UPDATED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2024-05-15T19:37:00.917Z",
      "expiresAt": "2024-06-14T19:37:00.917Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PERSON_ACCOUNT_HOLDER_IDENTITY_UPDATED",
      "node": {
        "__typename": "PersonAccountHolderIdentityUpdatedEvent",
        "createdAt": "2024-05-15T19:36:59.225Z",
        "personAccountHolder": {
          "__typename": "USPersonAccountHolder",
          "id": "ACCOUNT_HOLDER_ID"
        },
        "updateTypes": ["FULL_LEGAL_NAME"]
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1715801821319
  }
}

Application Status

Application status notification events are triggered when an account holder or authorized user card product application transitions states. The following table provides an overview of some fields you may see in an application status event response. For a full list of response fields, refer to the API Reference:

FieldDescription
applicationStateThe status of the application
updatedAtThe time the application status was last updated

Account Holder Application Status

Account holder application status notifications are triggered when a card product application transitions states. The following notification events are available for account holder application statuses:

Notification EventAPI Reference
CARD_PRODUCT_APPLICATION_APPROVEDObject reference
CARD_PRODUCT_APPLICATION_IN_REVIEWObject reference
CARD_PRODUCT_APPLICATION_MANUAL_REVIEWObject reference
CARD_PRODUCT_APPLICATION_DOCUMENT_UPLOAD_REQUESTEDObject reference
CARD_PRODUCT_APPLICATION_DENIEDObject reference
CARD_PRODUCT_APPLICATION_UNDERWRITING_DECISION_REQUESTEDObject reference

The following payload provides an example notification response from an CARD_PRODUCT_APPLICATION_APPROVED event:

CARD_PRODUCT_APPLICATION_APPROVED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "id": "NOTIFICATION_EVENT_ID",
      "createdAt": "2022-02-23T22:22:03.830Z",
      "name": "CARD_PRODUCT_APPLICATION_APPROVED",
      "node": {
        "__typename": "AccountHolderCardProductApplication",
        "id": "ACCOUNT_HOLDER_CARD_PRODUCT_APPLICATION_ID",
        "createdAt": "2022-02-23T22:21:58.759Z",
        "updatedAt": "2022-02-23T22:22:01.475Z",
        "applicationState": {
          "status": "APPROVED"
        }
      }
    }
  },
  "extensions": {
    "requestId": "b5920a0f-ce66-9b8f-964a-6b5166e88dd2"
  }
}

Authorized user application status

Authorized user application status events are triggered when an authorized user's card product application transitions states. The following notification events are available for authorized user application statuses:

NOTIFICATION EVENT NAMEAPI Reference
AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_APPROVEDObject reference
AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_DENIEDObject reference
AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_CLOSEDObject reference
AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_MANUAL_REVIEWObject reference
AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_UNDERWRITING_DECISION_REQUESTEDObject reference
AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_DOCUMENT_UPLOAD_REQUESTEDObject reference

The following payload provides an example response for an AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_APPROVED event:

AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_APPROVED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "id": "NOTIFICATION_EVENT_ID",
      "createdAt": "2022-02-23T22:22:03.830Z",
      "name": "AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_APPROVED",
      "node": {
        "__typename": "AuthorizedUserCardProductApplication",
        "id": "AUTHORIZED_USER_CARD_PRODUCT_APPLICATION_ID",
        "createdAt": "2022-02-23T22:21:58.759Z",
        "updatedAt": "2022-02-23T22:22:01.475Z",
        "applicationState": {
          "status": "APPROVED"
        }
      }
    }
  },
  "extensions": {
    "requestId": "ID"
  }
}

Chargebacks and disputes

Chargeback and dispute notification events are triggered for various dispute-related events. The following table provides an overview of some of the fields you may see in a chargeback or dispute notification event response. For a full list of fields, refer to the API reference:

FieldDescription
statusThe status of the event type
creditStatusThe status of a provisional credit; applies to CHARGEBACK events

Chargeback provisional credit status

Chargeback provisional credit status events are triggered when a dispute case's provisional credit status is updated. The following notification events are available for chargeback provisional credit status events:

Notification Event NameAPI Reference
PAYMENT_CARD_TRANSACTION_CHARGEBACK_PROVISIONAL_CREDIT_ISSUEDObject reference
PAYMENT_CARD_TRANSACTION_CHARGEBACK_PROVISIONAL_CREDIT_REVOKEDObject reference

The following payload provides an example notification response from a PAYMENT_CARD_TRANSACTION_CHARGEBACK_PROVISIONAL_CREDIT_ISSUED event:

PAYMENT_CARD_TRANSACTION_CHARGEBACK_PROVISIONAL_CREDIT_ISSUED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "",
      "id": "",
      "name": "PAYMENT_CARD_TRANSACTION_CHARGEBACK_PROVISIONAL_CREDIT_ISSUED",
      "node": {
        "__typename": "PaymentCardTransactionChargeback",
        "id": "CHARGEBACK_ID",
        "dispute": {
          "id": "DISPUTE_CASE_ID"
        },
        "creditStatus": "PROVISIONAL_CREDIT_ISSUED",
        "status": "RECEIVED",
        "createdAt": "2023-03-23T16:57:43.752Z",
        "updatedAt": "2023-03-23T16:57:43.752Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1666245348543
  }
}

Dispute case status

Dispute case status events are triggered when the state of a transaction's dispute case is updated. The following notification events are available for dispute case statuses:

Notification Event NameAPI Reference
PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_INITIATEDObject reference
PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_RESOLVED_WITH_DISPUTE_CREDITObject reference
PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_CASE_CARDHOLDER_WONObject reference
PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_CASE_CARDHOLDER_LOSTObject reference
PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_REJECTEDObject reference
PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_CANCELLEDObject reference

The following payload provides an example notification response from a PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_INITIATED event:

PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_INITIATED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "",
      "id": "",
      "name": "PAYMENT_CARD_TRANSACTION_DISPUTE_CASE_STATUS_INITIATED",
      "node": {
        "__typename": "PaymentCardTransactionDispute",
        "id": "DISPUTE_CASE_ID",
        "status": "INITIATED",
        "createdAt": "2023-03-23T16:57:43.752Z",
        "updatedAt": "2023-03-23T16:57:43.752Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1666245348543
  }
}

Collaborative application decisioning

When the collaborative application decisioning feature is enabled, you can subscribe to the following event informing you an application decision is requested:

Notification EventAPI Reference
CARD_PRODUCT_APPLICATION_UNDERWRITING_DECISION_REQUESTEDObject reference

The following payload provides an example notification response from a CARD_PRODUCT_APPLICATION_UNDERWRITING_DECISION_REQUESTED event:

CARD_PRODUCT_APPLICATION_UNDERWRITING_DECISION_REQUESTED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-12-12T16:32:49.125Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "CARD_PRODUCT_APPLICATION_UNDERWRITING_DECISION_REQUESTED",
      "node": {
        "__typename": "AccountHolderCardProductApplication",
        "applicationState": {
          "status": "PENDING"
        },
        "createdAt": "2022-12-12T16:32:44.499Z",
        "id": "APPLICATION_ID",
        "updatedAt": "2022-12-12T16:32:44.499Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1670862772620
  }
}

Digital wallet token status

Digital wallet token notification events are triggered when a tokenized card is activated, suspended, or terminated. The following notification events are available for digital wallet token statuses:

Notification event nameAPI Reference
CARD_DIGITAL_WALLET_TOKEN_ACTIVATEDObject reference
CARD_DIGITAL_WALLET_TOKEN_SUSPENDEDObject reference
CARD_DIGITAL_WALLET_TOKEN_TERMINATEDObject reference

The following payload provides an example notification response from a CARD_DIGITAL_WALLET_TOKEN_ACTIVATED event:

DIGITAL_WALLET_TOKEN_ACTIVATED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-12-12T16:32:49.125Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "DIGITAL_WALLET_TOKEN_ACTIVATED",
      "node": {
        "__typename": "CardDigitalWalletTokenEvent",
        "paymentCardId": "PAYMENT_CARD_ID",
        "tokenStatus": "ACTIVE",
        "tokenPreviousStatus": "SUSPENDED",
        "reason": "DEVICE_FOUND"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1670862772620
  }
}

Document upload session

Document upload session events are sent when a new document upload session is requested.

Notification Event NameAPI Reference
CARD_PRODUCT_APPLICATION_DOCUMENT_UPLOAD_REQUESTEDObject reference

The following payload provides an example notification response of a CARD_PRODUCT_APPLICATION_DOCUMENT_UPLOAD_REQUESTED event:

CARD_PRODUCT_APPLICATION_DOCUMENT_UPLOAD_REQUESTED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2023-02-08T15:41:56.871Z",
      "name": "CARD_PRODUCT_APPLICATION_DOCUMENT_UPLOAD_REQUESTED",
      "expiresAt": "2023-03-10T15:41:56.873Z",
      "node": {
        "id": "APPLICATION_ID",
        "applicationState": {
          "status": "IN_REVIEW"
        },
        "updatedAt": "2023-02-08T15:41:54.831Z",
        "__typename": "AccountHolderCardProductApplication",
        "createdAt": "2023-02-07T21:27:06.955Z",
        "agentServicingRestrictedDetails": {
          "memo": "Document upload sessions"
        }
      },
      "id": "NOTIFICATION_EVENT_ID"
    }
  },
  "extensions": {
    "signatureTimestamp": 1675871903487
  }
}

External bank account

External bank account events are triggered when an external bank account is added or removed from an account holder. The following notification events are available for external bank account events:

Notification Event NameAPI Reference
EXTERNAL_BANK_ACCOUNT_ADDEDObject reference
EXTERNAL_BANK_ACCOUNT_REMOVEDObject reference

The following payload provides an example notification event response for an EXTERNAL_BANK_ACCOUNT_REMOVED event:

EXTERNAL_BANK_ACCOUNT_REMOVED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-11-04T06:53:59.966Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "EXTERNAL_BANK_ACCOUNT_REMOVED",
      "node": {
        "__typename": "ExternalBankAccountRemovedEvent",
        "id": "EXTERNAL_BANK_ACCOUNT_REMOVED_EVENT_ID",
        "accountHolderId": "ACCOUNT_HOLDER_ID",
        "accountName": "Plaid Checking",
        "accountStatus": "CLOSED",
        "createdAt": "2022-11-04T06:53:27.627Z",
        "externalBankAccountDetail": {
          "__typename": "ExternalBankAccountDetail",
          "id": "EXTERNAL_BANK_ACCOUNT_ID",
          "createdAt": "2022-11-04T06:53:27.627Z",
          "last4": "9606",
          "routingNumber": "011401533",
          "type": "CHECKING",
          "updatedAt": "2022-11-04T06:53:27.672Z"
        },
        "provider": "SIMULATED",
        "removedAt": "2022-11-04T06:53:58.700Z",
        "updatedAt": "2022-11-04T06:53:58.737Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1667544843895
  }
}

Financial account attributes

Financial account attribute events are triggered when financial account attributes are added or removed. The following notification events are available for financial account attributes:

Notification Event NameAPI Reference
FINANCIAL_ACCOUNT_ATTRIBUTE_ADDED_DELINQUENTObject reference
FINANCIAL_ACCOUNT_ATTRIBUTE_REMOVED_DELINQUENTObject reference
FINANCIAL_ACCOUNT_ATTRIBUTE_ADDED_DELINQUENT_SUSPENDEDObject reference
FINANCIAL_ACCOUNT_ATTRIBUTE_REMOVED_DELINQUENT_SUSPENDEDObject reference
FINANCIAL_ACCOUNT_ATTRIBUTE_ADDED_CHARGE_OFFObject reference
FINANCIAL_ACCOUNT_ATTRIBUTE_REMOVED_CHARGE_OFFObject reference

The following payload provides an example notification event response for an FINANCIAL_ACCOUNT_ATTRIBUTE_ADDED_DELINQUENT event:

FINANCIAL_ACCOUNT_ATTRIBUTE_ADDED_DELINQUENT
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2023-02-15T23:34:16.399Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "FINANCIAL_ACCOUNT_ATTRIBUTE_ADDED_DELINQUENT",
      "node": {
        "__typename": "FinancialAccount",
        "accountAttributes": ["DELINQUENT"],
        "accountStatus": "ACTIVE",
        "createdAt": "2023-02-15T23:34:03.095Z",
        "externalId": "EXTERNAL_ID",
        "id": "FINANCIAL_ACCOUNT_ID",
        "name": "Test PIF Commercial Credit Account"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1676504056802
  }
}

Financial account status

Financial account status events are triggered when a financial account transitions states. The following notification events are available for financial account statuses:

Notification Event NameAPI Reference
ACCOUNT_STATUS_ACTIVEObject reference
ACCOUNT_STATUS_UNDER_REVIEWObject reference
ACCOUNT_STATUS_SUSPENDEDObject reference
ACCOUNT_STATUS_PENDING_CLOSUREObject reference
ACCOUNT_STATUS_CLOSEDObject reference

The following payload provides an example notification event response for an ACCOUNT_STATUS_SUSPENDED event:

ACCOUNT_STATUS
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-10-20T05:55:45.841Z",
      "id": "nee_6f9f952070c8d0a6c446e3764bc905e3",
      "name": "ACCOUNT_STATUS_SUSPENDED",
      "node": {
        "__typename": "AccountStatusSuspendedEvent",
        "accountName": "My Sample Account",
        "createdAt": "2022-10-20T05:55:40.505Z",
        "externalId": "D5LDSYLPMR",
        "id": "ac_c022c3165221cf7546ca9db0ccd480831234"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1666245348543
  }
}

Internal transfer

Internal transfer notification events are triggered when any internal Highnote transfer transitions states. Internal transfer types represent the direction of money movement within Highnote, including:

  • From a funding financial account to a payment card financial account
  • From a payment card financial account to a funding financial account

The following table provides an overview of some of the fields you may see in an internal transfer notification event response. Note that this table does not contain all response fields. For a full list of response fields, refer to the API Reference:

FieldDescription
memoA description of the transfer for reference; input provided from your organization
internalTransferStatusThe current status of the internal transfer

Internal transfer from funding financial account

Internal transfers from funding financial account events are triggered when the internal transfer transitions states. The following notification events are available for internal transfer from funding financial accounts:

Notification EventAPI Reference
INTERNAL_TRANSFER_FROM_FUNDING_FINANCIAL_ACCOUNT_TO_PAYMENT_CARD_FINANCIAL_ACCOUNT_PENDINGObject reference
INTERNAL_TRANSFER_FROM_FUNDING_FINANCIAL_ACCOUNT_TO_PAYMENT_CARD_FINANCIAL_ACCOUNT_COMPLETEDObject reference
INTERNAL_TRANSFER_FROM_FUNDING_FINANCIAL_ACCOUNT_TO_PAYMENT_CARD_FINANCIAL_ACCOUNT_FAILEDObject reference

The following payload provides an example notification response from an INTERNAL_TRANSFER_FROM_FUNDING_FINANCIAL_ACCOUNT_TO_PAYMENT_CARD_FINANCIAL_ACCOUNT_PENDING event:

INTERNAL_TRANSFER_FROM_FUNDING_FINANCIAL_ACCOUNT_TO_PAYMENT_CARD_FINANCIAL_ACCOUNT
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-08-22T20:11:36.337Z",
      "id": "nee_8521b5febf49f4b19d7deb01dc0b5539",
      "name": "INTERNAL_TRANSFER_FROM_FUNDING_FINANCIAL_ACCOUNT_TO_PAYMENT_CARD_FINANCIAL_ACCOUNT_PENDING",
      "node": {
        "__typename": "InternalTransferFromFundingFinancialAccountToPaymentCardFinancialAccountPendingEvent",
        "amount": {
          "currencyCode": "USD",
          "value": 500000
        },
        "createdAt": "2022-08-22T20:11:32.302Z",
        "id": "ia_22dab11a1e0df343a89f7ecb53096bd32e",
        "internalTransferStatus": "PENDING",
        "updatedAt": "2022-08-22T20:11:32.302Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1661199096776
  }
}

Internal transfer from payment card financial account

Internal transfer from payment card financial account events are triggered when an internal transfer transitions states. The following notification events are available for internal transfer from payment card financial accounts:

Notification Event NameAPI Reference
INTERNAL_TRANSFER_FROM_PAYMENT_CARD_FINANCIAL_ACCOUNT_TO_FUNDING_FINANCIAL_ACCOUNT_PENDINGObject reference
INTERNAL_TRANSFER_FROM_PAYMENT_CARD_FINANCIAL_ACCOUNT_TO_FUNDING_FINANCIAL_ACCOUNT_COMPLETEDObject reference
INTERNAL_TRANSFER_FROM_PAYMENT_CARD_FINANCIAL_ACCOUNT_TO_FUNDING_FINANCIAL_ACCOUNT_FAILEDObject reference

The following payload provides an example notification response from an INTERNAL_TRANSFER_FROM_PAYMENT_CARD_FINANCIAL_ACCOUNT_TO_FUNDING_FINANCIAL_ACCOUNT_PENDING event:

INTERNAL_TRANSFER_FROM_PAYMENT_CARD_FINANCIAL_ACCOUNT_TO_FUNDING_FINANCIAL_ACCOUNT_PENDING
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-08-19T23:11:53.132Z",
      "id": "nee_49f8c163f4f8a2c47fe702f02fcbbf52",
      "name": "INTERNAL_TRANSFER_FROM_PAYMENT_CARD_FINANCIAL_ACCOUNT_TO_FUNDING_FINANCIAL_ACCOUNT_PENDING",
      "node": {
        "__typename": "InternalTransferFromPaymentCardFinancialAccountToFundingFinancialAccountPendingEvent",
        "amount": {
          "currencyCode": "USD",
          "value": 350000
        },
        "createdAt": "2022-08-19T23:11:51.931Z",
        "id": "ia_22e017a985a3034683aa55cef491902791",
        "internalTransferStatus": "PENDING",
        "updatedAt": "2022-08-19T23:11:51.931Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1660950715339
  }
}

Notification activation

NOTIFICATION_ACTIVATION events are ignored if provided as a subscription event name when adding a webhook.

Notification activation events are sent to your webhook to verify it's been set up correctly. This event will fire on the initial creation and when you attempt to reactivate a webhook.

Notification Event NameAPI Reference
NOTIFICATION_ACTIVATIONObject reference

The following payload provides an example notification event response from a NOTIFICATION_ACTIVATION event:

NOTIFICATION_ACTIVATION
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-10-21T19:14:46.664Z",
      "id": "nee_b0f306cc171b44ef89223ca68a0da569",
      "name": "NOTIFICATION_ACTIVATION",
      "node": {
        "__typename": "NotificationTargetActivationEvent",
        "ping": "pong"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1666379691368
  }
}

Payroll advance

Payroll advance notification events are triggered when the following payroll advance events occur:

  • Repayment completed
  • Write-off occurs

The following table provides an overview of some of the fields you may see in a payroll advance notification event response. Note that this table does not contain all response fields. For a full list of response fields, refer to the API Reference:

FieldDescription
employerFinancialAccountIdThe ID of the employer financial account sending the funds
financialAccountIdThe ID of the financial account receiving funds
payrollAdvanceThe details of the payroll advance related to the notification event
advanceAmountThe original amount of the payroll advance; part of the payrollAdvance details
amountAppliedThe amount that is deducted from the payroll advance outstanding balance; part of the payrollAdvance details
amountBeforeThe amount of the payroll advance that has yet to be repaid; part of the payrollAdvance details
balanceAfterThe balance amount due after amountApplied is applied and deducted from the payroll advance outstanding balance; part of the payrollAdvance details

Payroll advance repayment status

Payroll advance repayment status events are triggered when a payroll repayment is processed.

Notification Event NameAPI Reference
PAYROLL_ADVANCE_REPAYMENT_COMPLETEDObject reference

The following response codes are returned from a complete payroll repayment status event:

Payment Event StatusDescription
NOT_REPAIDStatus indicates that the payroll advance has not been paid
FULLY_REPAIDThe balance of the payroll advance is fully repaid.
PARTIALLY_REPAIDThe balance of the payroll advance is partially repaid.
WRITTEN_OFFThe payroll advance is written off on the Highnote platform because the 3 repayment AttemptCount was reached.

The following payload provides an example response from a PAYROLL_ADVANCE_REPAYMENT_COMPLETED event with a PARTIALLY_REPAID status response:

PAYROLL_ADVANCE_REPAYMENT
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-09-14T23:04:17.337Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PAYROLL_ADVANCE_REPAYMENT_COMPLETED",
      "node": {
        "id": "PAYROLL_ADVANCE_EVENT_ID",
        "employerFinancialAccountId": "FINANCIAL_ACCOUNT_ID",
        "payrollAdvance": {
          "advanceAmount": {
            "currencyCode": "USD",
            "value": 100000
          },
          "amountApplied": {
            "currencyCode": "USD",
            "value": 10000
          },
          "amountBefore": {
            "currencyCode": "USD",
            "value": 80000
          },
          "balanceAfter": {
            "currencyCode": "USD",
            "value": 70000
          },
          "id": "PAYROLL_ADVANCE_ID",
          "paymentAdvanceStatus": "PARTIALLY_REPAID",
          "repaymentAttemptCount": 3
        }
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1663196658157
  }
}

Payroll advance write off status

A payroll advance write off status event is sent when a payroll advance amount is written off.

Notification Event NameAPI Reference
PAYROLL_ADVANCE_WRITE_OFF_COMPLETEDObject reference

The following payload provides an example response body for a PAYROLL_ADVANCE_WRITE_OFF_COMPLETED event:

PAYROLL_ADVANCE_WRITE_OFF_COMPLETED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-09-14T23:04:27.797Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PAYROLL_ADVANCE_WRITE_OFF_COMPLETED",
      "node": {
        "id": "PAYROLL_ACCOUNT_TRANSFER_ID",
        "payrollAdvance": {
          "advanceAmount": {
            "currencyCode": "USD",
            "value": 100000
          },
          "amountApplied": {
            "currencyCode": "USD",
            "value": 0
          },
          "amountBefore": {
            "currencyCode": "USD",
            "value": 70000
          },
          "balanceAfter": {
            "currencyCode": "USD",
            "value": 0
          },
          "id": "PAYROLL_ADVANCE_ID",
          "paymentAdvanceStatus": "WRITTEN_OFF",
          "repaymentAttemptCount": 3,
          "writeOffAmount": {
            "currencyCode": "USD",
            "value": 70000
          }
        }
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1663196668260
  }
}

Payment card

Payment card notification events are triggered for various payment card-related events.

The following table provides an overview of some of the fields you may see in payment card notification event responses. Note that this table does not contain all response fields. For a full list of fields, see the API Reference:

FieldDescription
formFactorNotes whether the payment card is physical or virtual
previousStatusThe previous status of the payment card; applies to payment card status events
binThe Bank Identification Number (BIN) of the payment card
additionalNetworkDataNetwork specific transaction data
partialNotes whether the authorization was approved for a partial or full amount; applies to payment card authorization or authorization and clear events
paymentCardSnapshotA snapshot of the payment card at the time of the transaction event
transactionProcessingTypeThe CardTransactionProcessingType for the transaction

Payment card status

Payment card status events are triggered when a payment card transitions states. The following notification events are available for payment card statuses:

Notification Event NameAPI Reference
PAYMENT_CARD_ACTIVATEDObject reference
PAYMENT_CARD_SUSPENDEDObject reference
PAYMENT_CARD_UNSUSPENDEDObject reference
PAYMENT_CARD_CLOSEDObject reference

The following payload provides an example response body for a PAYMENT_CARD_ACTIVATED event:

PAYMENT_CARD_ACTIVATED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2021-12-02T18:12:13.408Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PAYMENT_CARD_ACTIVATED",
      "node": {
        "__typename": "PaymentCardActivatedEvent",
        "id": "PAYMENT_CARD_EVENT_ID",
        "bin": "510510",
        "cardProductId": "CARD_PRODUCT_ID",
        "expirationDate": "Sat Jan 01 08:00:00 UTC 2022",
        "formFactor": "VIRTUAL",
        "last4": "5100",
        "network": "MASTERCARD",
        "status": "ACTIVE",
        "previousStatus": "ACTIVATION_REQUIRED"
      }
    }
  },
  "extensions": { "signatureTimestamp": 1638843592782 }
}

Payment card authorization

Payment card authorization events are triggered when a transaction is authorized or transitions states. The following types of notification events are available for payment card authorizations:

Notification Event NameAPI Reference
PAYMENT_CARD_AUTHORIZATION_APPROVED Object reference
PAYMENT_CARD_AUTHORIZATION_DECLINED Object reference
PAYMENT_CARD_AUTHORIZATION_REVERSEDObject reference

The following payload provides an example response body from a PAYMENT_CARD_AUTHORIZATION_APPROVED event:

PAYMENT_CARD_AUTHORIZATION_APPROVED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2024-02-14T19:40:27.635Z",
      "expiresAt": "2024-03-15T19:40:27.642Z",
      "id": "nee_f7bf7cd4faa05f091801c288de8a1c30",
      "name": "PAYMENT_CARD_AUTHORIZATION_APPROVED",
      "node": {
        "__typename": "PaymentCardAuthorizationApprovedEvent",
        "accountHolderId": "ACCOUNT_HOLDER_ID",
        "additionalNetworkData": {
          "__typename": "VisaData",
          "transactionIdentifier": "38082a7f771345ce989e4574ff3252e4"
        },
        "approvedAmount": {
          "currencyCode": "USD",
          "value": 15000
        },
        "avsResponseCode": "NOT_PROVIDED",
        "cardId": "PAYMENT_CARD_ID",
        "createdAt": "2024-02-14T19:40:22.954Z",
        "currentFinancialAccountAvailableToSpendAmount": {
          "currencyCode": "USD",
          "value": 49925000
        },
        "currentFinancialAccountMaximumBalanceAmount": {
          "currencyCode": "USD",
          "value": 50000000
        },
        "cvvResponseCode": "MATCH",
        "financialAccountId": "FINANCIAL_ACCOUNT_ID",
        "id": "TRANSACTION_EVENT_ID",
        "merchantDetails": {
          "address": {
            "countryCodeAlpha3": "USA",
            "locality": "San Francisco",
            "postalCode": "94105",
            "region": "CA"
          },
          "category": "AUTOMATED_FUEL_DISPENSERS",
          "categoryCode": "5542",
          "countryCodeAlpha3": "USA",
          "description": "KWIK TRIP 123456",
          "merchantId": "MERCHANT_ID",
          "name": "My Awesome Fuel"
        },
        "partial": true,
        "paymentCardSnapshot": {
          "createdAt": "2024-02-14T19:40:22.954Z",
          "paymentCardCurrent": {
            "id": "PAYMENT_CARD_ID"
          },
          "status": "ACTIVE"
        },
        "pointOfServiceDetails": {
          "category": "AUTOMATED_FUEL_DISPENSER",
          "isCardHolderPresent": true,
          "isCardPresent": true,
          "isRecurring": false,
          "panEntryMode": "MAGNETIC_STRIPE",
          "pinEntryMode": "PIN_ENTRY_CAPABILITY",
          "terminalAttendance": "ATTENDED",
          "terminalSupportsPartialApproval": true
        },
        "postalCodeResponseCode": "NOT_PROVIDED",
        "requestedAmount": {
          "currencyCode": "USD",
          "value": 100
        },
        "responseCode": "APPROVED_FOR_PARTIAL_AMOUNT",
        "transactionId": "TRANSACTION_ID",
        "transactionProcessingType": "GOODS_AND_SERVICES"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1707939629312
  }
}

Payment card authorization and clear

Payment card authorization and clear events are triggered when a transaction is authorized and cleared or transitions states. The following notification events are available for payment card authorization and clear events:

Notification Event NameAPI Reference
PAYMENT_CARD_AUTHORIZATION_AND_CLEAR_APPROVEDObject reference
PAYMENT_CARD_AUTHORIZATION_AND_CLEAR_DECLINEDObject reference

The following payload provides an example of a PAYMENT_CARD_AUTHORIZATION_AND_CLEAR_APROVED event:

PAYMENT_CARD_AUTHORIZATION_AND_CLEAR_APPROVED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2024-02-14T19:45:09.082Z",
      "expiresAt": "2024-03-15T19:45:09.082Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PAYMENT_CARD_AUTHORIZATION_AND_CLEAR_APPROVED",
      "node": {
        "__typename": "PaymentCardAuthorizationAndClearDeclinedEvent",
        "accountHolderId": "ACCOUNT_HOLDER_ID",
        "additionalNetworkData": {
          "__typename": "VisaData",
          "transactionIdentifier": "a72be1cc26ea444697b8fa171f6bab6f"
        },
        "approvedAmount": {
          "currencyCode": "USD",
          "value": 1000
        },
        "avsResponseCode": "NOT_PROVIDED",
        "cardId": "PAYMENT_CARD_ID",
        "createdAt": "2024-02-14T19:45:04.386Z",
        "currentFinancialAccountAvailableToSpendAmount": {
          "currencyCode": "USD",
          "value": 49930000
        },
        "currentFinancialAccountMaximumBalanceAmount": {
          "currencyCode": "USD",
          "value": 50000000
        },
        "cvvResponseCode": "NOT_PROVIDED",
        "financialAccountId": "FINANCIAL_ACCOUNT_ID",
        "id": "TRANSACTION_EVENT_ID",
        "merchantDetails": {
          "address": {
            "countryCodeAlpha3": "USA",
            "locality": "Redmond",
            "postalCode": "98053",
            "region": "WA"
          },
          "category": "AUTOMATED_CASH_DISBURSE",
          "categoryCode": "6011",
          "countryCodeAlpha3": "USA",
          "description": "HIGHNOTE SF CA US 1234",
          "merchantId": "1234567890",
          "name": "HIGHNOTE_PLATFORM 1234"
        },
        "paymentCardSnapshot": {
          "createdAt": "2024-02-14T19:45:04.386Z",
          "paymentCardCurrent": {
            "id": "PAYMENT_CARD_ID"
          },
          "status": "ACTIVE"
        },
        "pointOfServiceDetails": {
          "category": "AUTOMATED_TELLER_MACHINE",
          "isCardHolderPresent": true,
          "isCardPresent": true,
          "isRecurring": false,
          "panEntryMode": "INTEGRATED_CIRCUIT_CARD",
          "pinEntryMode": "PIN_VERIFIED_BY_TERMINAL_DEVICE",
          "terminalAttendance": "UNATTENDED",
          "terminalSupportsPartialApproval": false
        },
        "postalCodeResponseCode": "NOT_PROVIDED",
        "requestedAmount": {
          "currencyCode": "USD",
          "value": 1000
        },
        "responseCode": "APPROVED",
        "transactionId": "TRANSACTION_ID",
        "transactionProcessingType": "CASH"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1707939909559
  }
}

Payment card cleared

Payment card cleared events are triggered when a transaction made using a payment card is cleared.

Notification Event NameAPI Reference
PAYMENT_CARD_CLEAREDObject reference

The following payload provides an example response body for a PAYMENT_CARD_CLEARED event:

PAYMENT_CARD_CLEARED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2024-02-14T19:44:18.646Z",
      "expiresAt": "2024-03-15T19:44:18.647Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PAYMENT_CARD_CLEARED",
      "node": {
        "__typename": "PaymentCardClearedEvent",
        "accountHolderId": "ACCOUNT_HOLDER_ID",
        "additionalNetworkData": {
          "__typename": "VisaData",
          "transactionIdentifier": "38082a7f771345ce989e4574ff3252e4"
        },
        "approvedAmount": {
          "currencyCode": "USD",
          "value": 10000
        },
        "avsResponseCode": "NOT_PROVIDED",
        "cardId": "PAYMENT_CARD_ID",
        "createdAt": "2024-02-14T19:44:18.148Z",
        "currentFinancialAccountAvailableToSpendAmount": {
          "currencyCode": "USD",
          "value": 49930000
        },
        "currentFinancialAccountMaximumBalanceAmount": {
          "currencyCode": "USD",
          "value": 50000000
        },
        "cvvResponseCode": "MATCH",
        "financialAccountId": "FINANCIAL_ACCOUNT_ID",
        "id": "TRANSACTION_EVENT_ID",
        "merchantDetails": {
          "address": {
            "countryCodeAlpha3": "USA",
            "locality": "San Francisco",
            "postalCode": "94105",
            "region": "CA"
          },
          "category": "AUTOMATED_FUEL_DISPENSERS",
          "categoryCode": "5542",
          "countryCodeAlpha3": "USA",
          "description": "The awesomest awesome fuel dispensers",
          "merchantId": "Merchant Id",
          "name": "My Awesome Fuel"
        },
        "partial": true,
        "paymentCardSnapshot": {
          "createdAt": "2024-02-14T19:44:18.148Z",
          "paymentCardCurrent": {
            "id": "PAYMENT_CARD_ID"
          },
          "status": "ACTIVE"
        },
        "pointOfServiceDetails": {
          "category": "AUTOMATED_FUEL_DISPENSER",
          "isCardHolderPresent": true,
          "isCardPresent": true,
          "isRecurring": false,
          "panEntryMode": "MAGNETIC_STRIPE",
          "pinEntryMode": "PIN_ENTRY_CAPABILITY",
          "terminalAttendance": "ATTENDED",
          "terminalSupportsPartialApproval": true
        },
        "postalCodeResponseCode": "NOT_PROVIDED",
        "requestedAmount": {
          "currencyCode": "USD",
          "value": 10000
        },
        "responseCode": "APPROVED",
        "transactionId": "TRANSACTION_ID",
        "transactionProcessingType": "GOODS_AND_SERVICES"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1707939859969
  }
}

Payment card verification

Payment card verification events are triggered when a verification is either approved or denied. The following notification events are available for payment card verification:

Notification Event NameAPI Reference
PAYMENT_CARD_VERIFICATION_APPROVEDObject reference
PAYMENT_CARD_VERIFICATION_DECLINEDObject reference

The following payload provides an example response body for a PAYMENT_CARD_VERIFICATION_APPROVED event:

PAYMENT_CARD_VERIFICATION_APPROVED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-05-09T22:27:32.871Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PAYMENT_CARD_VERIFICATION_APPROVED",
      "node": {
        "__typename": "PaymentCardVerificationApprovedEvent",
        "approvedAmount": {
          "currencyCode": "USD",
          "value": 1
        },
        "paymentCardSnapshot": {
          "status": "ACTIVE",
          "paymentCardCurrent": {
            "id": "PAYMENT_CARD_ID"
          }
        },
        "avsResponseCode": "NOT_PROVIDED",
        "createdAt": "2022-05-09T22:27:31.636Z",
        "cvvResponseCode": "NOT_PROVIDED",
        "id": "PAYMENT_CARD_VERIFICATION_EVENT_ID",
        "financialAccountId": "FINANCIAL_ACCOUNT_ID",
        "accountHolderId": "ACCOUNT_HOLDER_ID",
        "paymentCardId": "PAYMENT_CARD_ID",
        "merchantDetails": {
          "merchantId": "000000000011111",
          "name": "Safeway",
          "category": "MISCELLANEOUS_SPECIALTY_RETAIL",
          "categoryCode": "5514",
          "address": {
            "postalCode": "94105",
            "region": "CA",
            "locality": "San Francisco",
            "countryCodeAlpha3": "USA"
          },
          "paymentCardSnapshot": {
            "createdAt": "2024-02-14T19:43:23.039Z",
            "paymentCardCurrent": {
              "id": "PAYMENT_CARD_ID"
            },
            "status": "ACTIVE"
          },
          "pointOfServiceDetails": {
            "category": "AUTOMATIC_FUEL_DISPENSER",
            "panEntryMode": "MAGNETIC_STRIPE",
            "pinEntryMode": "PIN_VERIFIED_BY_TERMINAL_DEVICE",
            "terminalAttendance": "ATTENDED",
            "isCardHolderPresent": true,
            "isCardPresent": true,
            "terminalSupportsPartialApproval": false,
            "isRecurring": false
          },
          "transactionProcessingType": "PAYMENT_DEBIT",
          "postalCodeResponseCode": "NOT_PROVIDED",
          "requestedAmount": {
            "currencyCode": "USD",
            "value": 1
          },
          "responseCode": "APPROVED",
          "transactionId": "TRANSACTION_ID"
        }
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1652135254644
  }
}

Payment card transaction enhanced data

The payment card transaction enhanced data event is received is enhanced data is received from the card network.

Notification Event NameAPI Reference
PAYMENT_CARD_ENHANCED_DATA_RECEIVEDObject reference

The following payload provides an example response body for a PAYMENT_CARD_ENHANCED_DATA_RECEIVED event:

PAYMENT_CARD_ENHANCED_DATA_RECEIVED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2023-04-01T00:55:18.566Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PAYMENT_CARD_ENHANCED_DATA_RECEIVED",
      "node": {
        "__typename": "PaymentCardEnhancedDataEvent",
        "accountHolderId": "ACCOUNT_HOLDER_ID",
        "additionalNetworkData": {
          "__typename": "VisaData",
          "transactionIdentifier": "63e2d6aaaef24f5d9cab99af689c5a21"
        },
        "cardId": "cd_b47701ed1fe71b98acb2d67c710a912d",
        "createdAt": "2023-04-01T00:55:16.495Z",
        "financialAccountId": "FINANCIAL_ACCOUNT_ID",
        "id": "TRANSACTION_EVENT_ID",
        "responseCode": "APPROVED",
        "transactionId": "TRANSACTION_ID",
        "transactionProcessingType": "GOODS_AND_SERVICES"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1680310520414
  }
}

Physical card order

Physical card order notification events are triggered for various physical card order-related events.

The following table provides an overview of some fields you may see in a physical card order notification event response. Note that this table does not contain all response fields. For a full list, see the API Reference:

FieldDescription
orderStateDetails of the payment card order state and status; applies to single payment card order events
cardCountNumber of payment cards in the group order; applies to group order events
groupOrderStateDetails of the payment card order state and status; applies to group order events

Physical card fulfillment

Physical card fulfillment events are triggered when a physical payment card shipment fulfillment changes states. The following notification events are available for physical card fulfillment:

Notification Event NameAPI Reference
PHYSICAL_PAYMENT_CARD_SHIPPEDObject reference
PHYSICAL_PAYMENT_CARD_SHIP_FAILEDObject reference

The following payload provides an example response body for a PHYSICAL_PAYMENT_CARD_GROUP_ORDER_SHIPPED event:

PHYSICAL_PAYMENT_CARD_SHIPPED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-04-08T00:57:05.589Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PHYSICAL_PAYMENT_CARD_SHIPPED",
      "node": {
        "__typename": "PhysicalPaymentCardShippedEvent",
        "createdAt": "2022-04-08T00:56:46.242Z",
        "id": "PHYSICAL_PAYMENT_CARD_EVENT_ID",
        "orderState": {
          "status": "SHIPPED"
        },
        "paymentCardId": "PAYMENT_CARD_ID",
        "updatedAt": "2022-04-08T00:57:03.588Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1649379429987
  }
}

Physical card group order

Physical card group order events are triggered when a group card order shipment ships or fails. The following notification events are available for physical card group orders:

Notification Event NameAPI Reference
PHYSICAL_PAYMENT_CARD_GROUP_ORDER_SHIPPEDObject reference
PHYSICAL_PAYMENT_CARD_GROUP_ORDER_SHIP_FAILEDObject reference

The following payload provides an example response body for a PHYSICAL_PAYMENT_CARD_GROUP_ORDER_SHIPPED event:

PHYSICAL_PAYMENT_CARD_GROUP_ORDER_SHIPPED
{
  "data": {
    "node": {
      "__typename": "NotificationEvent",
      "createdAt": "2022-10-25T22:28:02.991Z",
      "id": "NOTIFICATION_EVENT_ID",
      "name": "PHYSICAL_PAYMENT_CARD_GROUP_ORDER_SHIPPED",
      "node": {
        "__typename": "PhysicalPaymentCardGroupOrderShippedEvent",
        "cardCount": 1,
        "cardProductId": "CARD_PRODUCT_ID",
        "createdAt": "2022-10-25T22:24:53.923Z",
        "groupOrderState": {
          "status": "SHIPPED"
        },
        "id": "PHYSICAL_PAYMENT_CARD_GROUP_ORDER_EVENT_ID",
        "updatedAt": "2022-10-25T22:27:58.019Z"
      }
    }
  },
  "extensions": {
    "signatureTimestamp": 1666736885597
  }
}

Provide Feedback

Was this content helpful?